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Preface 


This book is intended for system programmers who use the IBM data 
management access methods—other than VS AM (virtual storage access 
method)—to process data sets. This book does not cover such specialized 
applications as time sharing option (TSO), graphics, teleprocessing, optical 
character readers, optical reader —sorters, and magnetic character readers. These 
specialized applications are described in separate publications listed in IBM 
Systemj370 and 4300 Processors Bibliography , GC20-0001. 

To learn about VS AM or to write programs that create and process VS AM data 
sets, see: 

• MVS/Extended Architecture Catalog Administration Guide , GC26-4041, 
which describes how to create master and user catalogs 

• MVS!Extended Architecture VSAM Administration Guide , GC26-4015, 
which describes how to create VSAM data sets 

• MVS I Extended Architecture Integrated Catalog Administration: Access 
Method Services Reference , GC26-4019, and MVS j Extended Architecture 
VSAM Catalog Administration: Access Method Services Reference , 
GC26-4075, which describe the access method services commands used to 
manipulate VSAM data sets 

• MVS I Extended Architecture VSAM Administration: Macro Instruction 
Reference , GC26-4016, which describes how to code the macro instructions 
required with VSAM data sets 


Organization 


This publication has 15 chapters and 4 appendixes: 

• Chapter 1, “Introduction to Data Administration” on page 1, provides an 
overview of data set processing, including a description of four different 
access methods, and a discussion of data set identification. 

• Chapter 2, “Data Set Storage” on page 5, discusses the characteristics of 
data sets that are stored on direct access and magnetic tape devices. 

• Chapter 3, “Record Formats” on page 13, discusses the considerations for 
creating and processing records within the various kinds of record formats. 
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• Chapter 4, “Selecting an Access Method” on page 35, gives an overview of 
basic and sequential access methods in data management, and compares the 
functions and performance of each. 

• Chapter 5, “Specifying a Data Control Block and Initializing Data Sets” on 
page 41, discusses how to specify a DCB and how to open and close data 
sets. This chapter also discusses managing buffer pools and handling data set 
volumes. 

• Chapter 6, “Accessing Records in Data Sets” on page 61, discusses how to 
use GET and PUT or READ and WRITE macros to access data records. 
This chapter also discusses analyzing input and output errors. 

• Chapter 7, “DCB Exit Routines” on page 75, discusses user-written exit 
routines and the parameter lists they use. 

• Chapter 8, “Spooling and Scheduling Data Sets” on page 105, discusses how 
to route data through the input/output streams of the job entry subsystem 
(JES). 

• Chapter 9, “Processing a Sequential Data Set” on page 109, discusses 
managing sequential data sets and buffers. 

• Chapter 10, “Processing a Partitioned Data Set” on page 131, discusses the 
advantages and restrictions of partitioned data sets. 

• Chapter 11, “Processing a Direct Data Set” on page 149, discusses the tasks 
required to process BDAM data sets. 

• Chapter 12, “Processing an Indexed Sequential Data Set” on page 159, 
discusses the organization of and the access techniques for ISAM data sets. 

• Chapter 13, “Generation Data Groups” on page 193, discusses the reasons 
for using generation data groups and how to specify them. 

• Chapter 14, “I/O Device Control Macros” on page 201, discusses the macro 
instructions that control input and output devices. 

• Chapter 15, “Protecting Data” on page 205, discusses password and 
Resource Access Control Facility (RACF) protection of non-VSAM data 
sets. 

• Appendix A, “Direct Access Labels” on page 209, discusses the standard 
label formats used on direct access volumes. 

• Appendix B, “Control Characters” on page 213, discusses the use of an 
optional control character to control card punches and printers. 
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• Appendix C, “Allocating Space on Direct Access Volumes” on page 217, 
discusses methods of estimating capacities and space requirements on direct 
access devices. 

• Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 
Word” on page 223, discusses the translation of ISO/ANSI/FIPS record 
control words and ISO/ANSI/FIPS segment control words. 


Prerequisite Knowledge 

To use this book efficiently, you should be familiar with: 

• Assembler language 

• Job control language 


Required Publications 

You should be familiar with the information presented in the following 
publications: 

• Assembler H Version 2 Application Programming: Guide , SC26-4036 

• Assembler H Version 2 Application Programming: Language Reference , 
GC26-4037 

• MVS I Extended Architecture JCL User's Guide , GC28-1351 

• MVS!Extended Architecture JCL Reference , GC28-1352 


Related Publications 


Within the text, references are made to the publications listed below: 


Short Title 

Publication Title 

Order Number 

Assembler H V2 

Application 

Programming: 

Guide 

Assembler H Version 2 
Application Programming: 

Guide 

SC26-4036 

Assembler H V2 
Application 
Programming: 
Language 

Reference 

Assembler H Version 2 
Application Programming: 
Language Reference 

GC26-4037 
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Short Title 

Publication Title 

Order Number 

Data 

Administration: 

Macro Instruction 
Reference 

MVSj Extended Architecture 

Data Administration: Macro 
Instruction Reference 

GC26-4014 

Debugging 

Handbook 

MVS/Extended Architecture 
Debugging Handbook , 

Volumes 1 through 5 

LC28-1164 1 
LC28-1165 
LC28-1166 
LC28-1167 
LC28-1168 

Device Support 
Facilities User's 

Guide and 

Reference 

Device Support Facilities User's 
Guide and Reference 

GC35-0033 

IBM 3262 Model 5 
Printer Product 
Description 

IBM 3262 Model 5 Printer 
Product Description 

GA24-3936 

IBM 3800 Printing 

Subsystem 

Programmer's 

Guide 

IBM 3800 Printing Subsystem 
Programmer s Guide 

GC26-3846 

IBM 3800 Printing 

Subsystem 

Programmer's 

Guide 

IBM 3800 Printing Subsystem 
Models 3 and 8 Programmer's 
Guide 

SH35-0061 

IBM 3890 

Document 

Processor Machine 
and Programming 
Description 

IBM 3890 Document Processor 
Machine and Programming 
Description 

GA24-3612 

IBM 4245 Printer 
Model 1 

Component 
Description and 
Operator's Guide 

IBM 4245 Printer Model I 
Component Description and 
Operator's Guide 

GA33-1541 

IBM 4248 Printer 
Model 1 

Description 

IBM 4248 Printer Model I 
Description 

GA24-3927 

Initialization and 
Tuning 

MVS!Extended Architecture 
System Programming Library: 
Initialization and Tuning 

GC28-1149 

JCL User's Guide 

MVS/Extended Architecture 

JCL User's Guide 

GC28-1351 

JCL Reference 

MVSj Extended Architecture 

JCL Reference 

GC28-1352 


Note: 

1 All five volumes may be ordered under one order number, LBOF-1015. 
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Short Title 

Publication Title 

Order Number 

Magnetic Tape 

Labels and File 

Structure 

Administration 

MVS 1 Extended Architecture 
Magnetic Tape Labels and File 
Structure Administration 

GC26-4145 

Open/Close/EOV 

Logic 

MVS 1 Extended Architecture 
Open/Close/EOV Logic 

LY26-3892 

OS/VS IBM 3886 
Optical Character 
Reader Model 1 
Reference 

OS/ VS IBM 3886 Optical 
Character Reader Model 1 
Reference 

GC24-5101 

OS/VS Mass 

Storage System 
(MSS) Planning 
Guide 

OS/VS Mass Storage System 
(MSS) Planning Guide 

GC35-0011 

OS/VS Mass 

Storage System 
(MSS) Services: 
General 

Information 

OS/ VS Mass Storage System 
(MSS) Services: General 
Information 

GC35-0016 

OS/VS Mass 

Storage System 
(MSS) Extensions 
Services: Reference 

OS/VS Mass Storage System 
(MSS) Extensions Services: 
Reference 

SH35-0036 

Programming 

Support for the 

IBM 3505 Card 
Reader and the 

IBM 3525 Card 
Punch 

Programming Support for the 
IBM 3505 Card Reader and 
the IBM 3525 Card Punch 

GC21-5097 

RACF General 
Information 

Manual 

Resource Access Control 

Facility (RACF): General 
Information Manual 

GC28-0722 

Service Aids 

MVS/Extended Architecture 
System Programming Library: 
Service A ids 

GC28-1159 

Supervisor Services 
and Macro 
Instructions 

MVS/Extended Architecture 
System Programming Library: 

1 Supervisor Services and Macro 
Instructions 

GC28-1154 

System Codes 

MVS/Extended Architecture 
Message Library: System 

Codes 

GC28-1157 

System — Data 
Administration 

MVS/Extended Architecture 
System — Data Administration 

GC26-4010 

System Generation 

MVS/Extended Architecture 
Installation: System Generation 

GC26-4009 
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Short Title 

Publication Title 

Order Number 

System Macros and 
Facilities 

MVS!Extended Architecture 
System Programming Library: 
Macros and Facilities, Volumes 

1 and 2 

GC28-1150 

and 

GC28-1151 

System Messages 

MVS!Extended Architecture 
Message Library: System 
Messages , Volumes 1 and 2 

GC28-1376 

and 

GC28-1377 

Utilities 

MVS/Extended Architecture 

Data Administration: Utilities 

GC26-4018 
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Summary of Changes 


I Release 1.2 Library Update, January 1987 


| Service Changes 


Information has been added, corrected, or deleted to reflect technical service 
changes. 


Release 1.2, February 1984 

This publication, formerly titled M VS/Extended Architecture Data Management 
Services , is now titled MVS)Extended Architecture Data Administration Guide. 
The publication has been reorganized for ease of use. 


New Device Support 


The IBM 3800 Printing Subsystem Model 3 is now supported in Model 1 
compatibility mode. 

Modifications have been made to the SETPRT macro to support the IBM 4248, 
3262 Model 5, and 4245 printers. 

Note: The IBM 3262 Model 5 printer is afforded the same support as that 
provided for the IBM 4248 printer. However, the use of an IBM 3262 Model 5 
printer dictates that entries exist in the IBM 4248 printer UCS Image Table for 
the IBM 3262 Model 5 printer band(s)/alias(es) used on the host system. These 
image table entries must be generated by the user as part of the IBM 3262 Model 
5 installation procedure. 

Information to support the IBM 3800 Printing Subsystem Model 3 in full 
function and Model 1 compatibility mode has been added to the SYNAD 
parameter of the DCB and SETPRT macros. 


Summary of Changes IX 
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Chapter 1. Introduction to Data Administration 


Data administration is the process of systematically and effectively organizing, 
identifying, storing, cataloging, and retrieving all the information (including 
programs) that your installation uses. 

Data set storage control, along with an extensive catalog system, makes it 
possible to retrieve data by symbolic name alone, without specifying device types 
and volume serial numbers. In freeing computer personnel from maintaining 
complicated volume serial number inventory lists of stored data and programs, 
the catalog reduces manual intervention and the likelihood of human error. 

A data set is a collection of logically related data records that are stored on a 
volume and that may be classified according to installation needs. For example, 
a sales department could classify its data by geographic area, by individual 
salesperson, or by any other logical plan. A user can request data from a direct 
access volume or a tape volume. 

The cataloging system makes it possible to classify successive generations or 
updates of related data. These generations can be given identical names and 
subsequently be referred to relative to the current generation. The system 
automatically maintains a list of the most recent generations. 

Data administration provides: 

• Allocation of space on direct access volumes. 

• Automatic retrieval of cataloged data sets by name alone. 


Overview of Data Set Processing 

Input/output routines in the operating system schedule and control all data 
transfer operations between virtual and auxiliary storage. These routines can: 

• Read data 

• Write data 

• Translate data from ISCII/ASCII (International Standard Code for 
Information Interchange and American National Standard Code for 
Information Interchange) to EBCDIC (Extended Binary Coded Decimal 
Interchange Code) and the reverse 
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• Block and unblock records 

• Overlap reading, writing, and processing operations 

• Read and verify volume and data set labels 

• Write data set labels 

• Position and reposition volumes automatically 

• Detect I/O errors and correct them when possible 

• Provide exits to user-written error and label routines 

Data management programs also provide a variety of methods for gaining access 
to a data set. These methods are based on data set organization and data access 
technique. 

You can organize your data sets in one of four ways: 

• Sequential : Records are organized in physical rather than logical sequence. 
Given one record, the location of the next record is determined by its 
physical position in the data set. You must use the sequential data set 
organization for all magnetic tape devices, but it is optional on direct access 
devices. Punched cards and printed output must also be sequentially 
organized. 

• Indexed Sequential: Records are arranged in sequence, according to a key 
that is a part of every record, on the tracks of a direct access volume. An 
index or set of indexes maintained by the system gives the location of certain 
principal records. This permits direct and sequential access to any record. 

• Direct: Records within the data set, which must be on a direct access 
volume, may be organized in any manner you choose. All space allocated to 
the data set is available for data records. No space is required for indexes. 
You specify addresses by which records are stored and retrieved directly. 

• Partitioned: Independent groups of sequentially organized records, called 
members, are in direct access storage. Each member has a simple name 
stored in a directory that is part of the data set and contains the location of 
the member's starting point. Partitioned data sets are generally used to store 
programs. As a result, they are often called libraries. 

Requests for input/output operations on data sets through macro instructions use 
two techniques: the technique for queued access and the technique for basic 
access. Each technique is identified according to its treatment of buffering and 
synchronization of input and output with processing. The combination of an 
access technique and a given data set organization is called an access method . In 
choosing an access method for a data set, therefore, you must consider not only 
its organization, but also what you need to specify through macros. Also, you 
may choose a data organization according to the access techniques and processing 
capabilities available. 
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The code generated by the macros for both techniques is optionally reenterable, 
depending on the form in which parameters are expressed. 

Besides the access methods provided by the operating system, an elementary 
access technique called execute channel program (EXCP) is also provided. To 
use this technique, you must establish your own system for organizing, storing, 
and retrieving data. The primary advantage of EXCP is the complete flexibility it 
allows you in using the computer directly. 

An important feature of data administration is that much of the detailed 
information needed to store and retrieve data, such as device type, buffer 
processing technique, and length of output records, need not be supplied until the 
job is ready to be executed. This device independence permits changes to those 
specifications to be made without changes in the program. Therefore, you may 
design and test a program without knowing the exact input/output devices that 
will be used when it is executed. 

Device independence is a feature of both the queued and basic access techniques 
for processing sequential data sets. To some extent, you can determine the 
degree of device independence. Many useful device-dependent features are 
available as part of certain macro instructions; achieving device independence 
requires some selectivity in their use. 


Identifying Data Sets 

Any information that is a named, organized collection of logically related records 
can be classified as a data set. The information is not restricted to a specific type, 
purpose, or storage medium. A data set may be, for example, a source program, 
a library of macros, or a file of data records used by a processing program. 

Whenever you indicate that a new data set is to be created and placed on 
auxiliary storage, you (or the operating system) must give the data set a name. 
The data set name identifies a group of records as a data set. All data sets 
recognized by name (referred to without volume identification) and all data sets 
residing on a given volume must be distinguished from one another by unique 
names. To help in this, the system provides a means of qualifying data set 
names. 

A data set name is one simple name or a series of simple names joined together 
so that each represents a level of qualification. For example, the data set name 
DEPT58.SMITH.DATA3 is composed of three simple names. Proceeding from 
the left, each simple name is a category within which the next simple name is a 
subcategory. The first name is called the high-level qualifier, the last is the 
low-level qualifier. 

Each simple name consists of from 1 to 8 alphameric characters, the first of 
which must be alphabetic. The special character period (.) separates simple 
names from each other. Including all simple names and periods, the length of the 
data set name must not exceed 44 characters. Thus, a maximum of 22 simple 
names can make up a data set name. 
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To permit different executions of a program to process different data sets without 
program reassembly, the data set is not referred to by name in the processing 
program. When the program is executed, the data set name and other pertinent 
information (such as unit type and volume serial number) are specified in a job 
control statement called the data definition (DD) statement. To gain access to 
the data set during processing, reference is made to a data control block (DCB) 
associated with the name of the DD statement. Space for a data control block 
that specifies the particular data set to be used is reserved by a DCB macro when 
your program is assembled. 
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Chapter 2. Data Set Storage 


The operating system provides a variety of devices for collecting, storing, and 
distributing data. Despite the variety, the devices have many common 
characteristics. The generic term volume is used to refer to a standard unit of 
auxiliary storage. A volume may be a reel of magnetic tape, a disk pack, or a 
drum. 

Each data set stored on a volume has its name, location, organization, and other 
control information stored in the data set label or volume table of contents (for 
direct access volumes only). Thus, when the name of the data set and the 
volume where it is stored are made known to the operating system, a complete 
description of the data set, including its location on the volume, can be retrieved. 
Then, the data itself can be retrieved, or new data added to the data set. 

Various groups of labels are used to identify magnetic tape and direct access 
volumes, and the data sets they contain. Magnetic tape volumes can have 
standard or nonstandard labels, or they can be unlabeled. Direct access volumes 
must use standard labels. Standard labels include a volume label, a data set label 
for each data set, and optional user labels. 

Keeping track of the volume where a particular data set resides can be a burden 
and a source of error. To alleviate this problem, the system provides for 
automatic cataloging of data sets. The system can retrieve a cataloged data set if 
given only the name of the data set. 

By use of the catalog, collections of data sets related by a common external name 
and the time sequence in which they were cataloged (their generation) can be 
identified; they are called generation data groups. For example, a data set name 
LAB.PAYROLL(O) refers to the most recent data set of the group; 
LAB.PAYROLL(-l) refers to the second most recent data set; and so forth. The 
same data set names can be used repeatedly with no need to keep track of the 
volume serial numbers used. For more information, see “Relative Generation 
Number” on page 194. 


Direct Access Volumes 

Regardless of organization, data sets created using the operating system can be 
stored on a direct access volume. Each block of data has a distinct location and a 
unique address, making it possible to find any record without extensive searching. 
Thus, records can be stored and retrieved either directly or sequentially. 
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Direct access volumes are used to store executable programs, including the 
operating system itself. Direct access storage (sometimes called DASD storage) is 
also used for data and for temporary working storage. One direct access storage 
volume may be used for many different data sets, and space on it may be 
reallocated and reused. A volume table of contents (VTOC) is used to account 
for each data set and available space on the volume. 

Each direct access volume is identified by a volume label that is stored at track 0 
of cylinder 0. You may specify as many as seven additional labels, located 
following the standard volume label, for further identification. 

The VTOC is a data set consisting of data set control blocks (DSCBs) that 
describe the contents of the direct access volume. The VTOC can contain seven 
kinds of DSCBs, each with a different purpose and a different format number. 
The format 0 DSCB describes an unused (available) record in the VTOC. 
System—Data Administration describes format 1 through format 6 DSCBs and 
their purposes. System—Data Administration also describes the structure of the 
VTOC. 

Each direct access volume is initialized by a utility program before being used on 
the system. The initialization program generates the volume label and builds the 
table of contents. For additional information on direct access labels, see 
Appendix A, “Direct Access Labels” on page 209. 

When a data set is to be stored on a direct access volume, you must supply the 
operating system with the amount of space to be allocated to the data set, 
expressed in blocks, tracks, or cylinders. Space allocation can be independent of 
device type if the request is expressed in blocks. If the request is made in tracks 
or cylinders, you must be aware of such device considerations as cylinder capacity 
and track size. 


Track Characteristics 


Although direct access devices differ in physical appearance, capacity, and speed, 
they are similar in data recording, data checking, data format, and programming. 
The recording surface of each volume is divided into many concentric tracks. 

The number of tracks and their capacity vary with the device. Each device has 
some type of access mechanism, containing read/write heads that transfer data as 
the recording surface rotates past them. 


Track Format 


Information is recorded on all direct access volumes in a standard format. 

Besides device data, each track contains a track descriptor record (capacity record 
or record 0) and data records. 

Figure 1 shows that there are two possible data record formats—count data and 
count key data—only one of which can be used for a particular data set. 


6 


MVS/'XA Data Administration Guide 






Count-Data Format 


Count 


Data 

Track Descriptor 
Record (RO) 

i 

Count 


Data 


Track Descriptor 
Record (RO) 


Count 


Data 



Count 


Data 


Data Record (R 1) 

Count-Key-Data Format 


Data Record (Rn) 


Count 


Key 


Data 



Count 


Key 


Data 


Data Record (R 1) 

Figure 1. Direct Access Volume Track Formats 


Data Record (Rn) 


Besides device data, the count area contains 8 bytes that identify the location of 
the record by cylinder, head, and record numbers, its key length (0 if no keys are 
used), and its data length. 

If the records are written with keys, the key area (1 to 255 bytes) contains a 
record key that specifies the data record by part number, account number, 
sequence number, or some other identifier. In some cases, records are written 
with keys so that they can be located quickly. 


Track Overflow 


If the record overflow feature is available for the direct access device being used, 
you can reduce the amount of unused space on the volume by specifying the 
track overflow option in the DCB parameter of the DD statement, or the DCB 
macro associated with the data set. If the overflow option is used, a block that 
does not fit on the track is partially written on that track and continued on the 
next track. (The track where the record is continued must be physically next and 
must be part of the same extent as the track that holds the first part of the 
record.) 

Each segment (the portion written on one track) of an overflow block has a 
count area. The data length field in the count area specifies the length of that 
segment only. If the block is written with a key, there is only one key area for 
the block. It is written with the first segment. If the track overflow option is not 
used, blocks are not split between tracks. 

Actual and Relative Addressing 

Two types of addresses can be used to store and retrieve data on a direct access 
volume: actual addresses and relative addresses. The only advantage of using 
actual addresses is the elimination of time required to convert from relative to 
actual addresses and vice versa. When sequentially processing a multiple volume 
data set, you can refer only to records of the current volume. 
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Actual Addresses: When the system returns the actual address of a record on a 
direct access volume to your program, it is in the form MBBCCHHR, where: 

M 

is a 1-byte binary number specifying the relative location of an entry in a 
data extent block (DEB). The DEB is created by the system when the data 
set is opened. Each extent entry describes a set of consecutive tracks 
allocated for the data set. 

BBCCHH 

is three 2-byte binary numbers specifying the cell (bin), cylinder, and head 
number for the record (its track address). The cylinder and head numbers 
are recorded in the count area for each record. 


R 

is a 1-byte binary number specifying the relative block number on the track. 
The block number is also recorded in the count area. 

If you use actual addresses in your program, the data set must be treated as 
unmovable. 

Relative Addresses: Two kinds of relative addresses can be used to refer to 
records in a direct access data set: relative block addresses and relative track 
addresses. 

The relative block address is a 3-byte binary number that shows the position of 
the block relative to the first block of the data set. Allocation of noncontiguous 
sets of blocks does not affect the number. The first block of a data set always 
has a relative block address of 0. 

The relative track address has the form TTR, where: 

‘XT 

is a 2-byte binary number specifying the position of the track relative to the 
first track allocated for the data set. The TT for the first track is 0. 
Allocation of noncontiguous sets of tracks does not affect the number. 

R 

is a l-byte binary number specifying the number of the block relative to the 
first block on the track TT. The R value for the first block of data on a 
track is 1. 


Magnetic Tape Volumes 

Because data sets on magnetic tape devices must be organized sequentially, the 
operating system does not require space allocation procedures comparable to that 
for direct access devices. When a new data set is to be placed on a magnetic tape 
volume, you must specify the data set sequence number if it is not the first data 
set on the reel. The operating system positions a volume with IBM standard 
labels, ISO/ANSI/FIPS labels, or no labels so that the data set can be read or 
written. If the data set has nonstandard labels, you must provide for volume 
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positioning in your nonstandard label processing routines. All data sets stored on 
a given magnetic tape volume must be recorded in the same density. 

When a data set is to be stored on an unlabeled tape volume and you have not 
specified a volume serial number, the system assigns a serial number to that 
volume and to any additional volumes required for the data set. Each such 
volume is assigned a serial number of the form Lxxxyy , where xxx is the data set 
sequence number, and yy is the volume sequence number for the data set. If you 
specify volume serial numbers for unlabeled volumes where a data set is to be 
stored, the system assigns volume serial numbers to any additional volumes 
required. If data sets residing on unlabeled volumes are to be cataloged or 
passed, you should specify the volume serial numbers for the volumes required. 
This ensures that data sets residing on different volumes are not cataloged or 
passed under identical volume serial numbers. Retrieving such data sets can give 
unpredictable errors. 

Each data set and data set label group must be followed by a tapemark. 
Tapemarks cannot exist within a data set. When the operating system creates a 
tape with standard labels or no labels, all tapemarks are automatically written. 
Two tapemarks follow the last trailer label group on a standard-label volume. 

On an unlabeled volume, the two tapemarks appear after the last data set. 

When the operating system creates data sets with nonstandard labels, no 
tapemarks are written. If you want the operating system to retrieve a data set, 
you must supply the tapemarks in your routine that creates the nonstandard-label 
volume. Otherwise, tapemarks are not required after nonstandard labels, because 
positioning of the tape volumes must be handled by installation routines. 

For more information about magnetic tape volume labels, see Magnetic Tape 
Labels and File Structure . 

The data on magnetic tape volumes can be in either EBCDIC or ISCII/ASCII. 
ISCII/ASCII is a 7-bit code consisting of 128 characters. It permits data on 
magnetic tape to be transferred from one computer to another, even though the 
two computers may be products of different manufacturers. 

Data management support of ISCII/ASCII and of the International Organization 
for Standardization (ISO), American National Standards Institute (ANSI), and 
Federal Information Processing Standard (FIPS) tape labels is such that data 
management can translate records' on input tapes in ISCII/ASCII into EBCDIC 
for internal processing and translate the EBCDIC into ISCII/ASCII for output. 
Records on such input tapes may be sorted into ISCII/ASCII collating sequence. 
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Cataloging Data Sets 


v,y 


The operating system has a catalog structure consisting of a master catalog, user 
catalogs, and, optionally, OS CVOLs. Figure 2 shows the catalog structure. 


Master Catalog 



1 111111 is the volume serial of the OS CVOL. 

Figure 2. Catalog Structure V.^ 


There is one master catalog on each system. It is required and contains entries 
for system data sets. It is also the VSAM or integrated catalog facility master 
catalog and does not have to be on the system residence volume. The master 
catalog contains a pointer to each user catalog. Both VSAM and non-VSAM 
data sets can be cataloged in a user catalog. 

Non-VSAM data sets can be cataloged on OS CVOLs (SYSCTLG data sets). 
The master catalog contains a pointer to each OS CVOL. Data sets can be 
cataloged, uncataloged, or recataloged. (For more information on using OS 
CVOLs, see Catalog Administration Guide.) If a data set is not cataloged in the 
master catalog, the first name of a qualified data set name indicates the user 
catalog or OS CVOL in which it is cataloged. A user catalog can also be 
connected to the system as a job catalog or a step catalog. 

Permanent Mass Storage System (MSS) data sets should be cataloged to allow 
efficient use of the mass storage volume control (MSVC) functions. For 
information on MSVC, see OSjVS Mass Storage System (MSS) Services: 
General Information. 


(f. x 
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Entering a Data Set Name in the Catalog 


The data set name of a non-VS AM data set can be entered in a master or user 
catalog through (1) job control language (DISP parameter), (2) access method 
services (DEFINE command), or (3) catalog management macro instructions 
(CATALOG and CAMLST). A non-VSAM data set name can be entered in an 
OS CVOL through JCL or the catalog management macros. VSAM data sets 
can only be cataloged by using access method services. 

Access method services is also used to establish aliases for data set names and to 
connect user catalogs and OS CVOLs to the master catalog. For information on 
how to use the access method services commands, see Access Method Services 
Reference. For information on how to use the catalog management macro 
instructions, see Catalog Administration Guide and System Data Administration. 

Data set names cannot be cataloged in an OS CVOL if a name is already 
cataloged whose levels match the highest or higher levels of the specified name. 
For example, the qualified name A.B.C.D cannot be cataloged if the name A.B 
or A.B.C is already cataloged, but the name A.B.C.D can be cataloged if AB.C 
or A.B.C.E is cataloged. This restriction is not true for data sets cataloged in an 
integrated catalog facility or VSAM catalog. 
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Chapter 3. Record Formats 


The record is the basic unit of information used by a processing program and can 
be anything from a single character to a mass of information collected by a 
particular business transaction, or measurements recorded at a given point in an 
experiment. A collection of logically related records makes up a data set. Most 
data processing consists of reading, manipulating, and writing individual records. 

Blocking is the process of grouping records before they are written on a volume. 

A block consists of one or more logical records written between consecutive 
interrecord gaps (IRGs). Blocking conserves storage space on a volume by 
reducing the number of IRGs in the data set and increases processing efficiency 
by reducing the number of input/output operations required to process the data 
set. 

Records are stored in one of four formats: fixed-length (format-F), variable-length 
for data in EBCDIC (format-V) or for data to be translated to or from 
ISCII/ASCII (format-D), or undefined-length (format-U). 

Before selecting a record format, you should consider: 

• The data type (for example, EBCDIC) your program will receive and the 
type of output it will produce 

• The input/output devices that will contain the data set 

• The access method you will use to read and write the records 

You identify your record format selection in the data control block using the 
options in the DCB macro, the DD statement, or the data set label. 

ISO/ANSI/FIPS tape records are written in format-F, format-D, format-S or 
format-U with the restrictions noted under “Fixed-Length Records, 
ISO/ANSI/FIPS Tapes” on page 15, “ISO/ANSI/FIPS Variable-Length 
Records—Format D” on page 23, and “Undefined-Length Records” on page 27. 

Note: Data can only be in format-U for ISO/ANSI Version 1 tapes (ISO 
1001-1969 and ANSI X3.27-1969). 

When data management reads records from ISO/ANSI/FIPS tapes, it translates 
the records into EBCDIC. When data management writes records onto 
ISO/ANSI/FIPS tapes, it translates the records into ISCII/ASCII characters. 
Because you use input records after they are translated and because output 
records are translated when you ask data management to write them, you work 
only with EBCDIC. 
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Note: Translation routines supplied by the system will convert to ASCII 7-bit 
code, as explained in Magnetic Tape Labels and File Structure. When the 
character to be translated contains a bit in the high order position, the 7-bit 
translation does not produce an equivalent character. Instead, it produces a 
substitute character to note the loss in translation. This means, for example, that 
random binary data (such as a dump) cannot be recorded in ISO/ANSI/FIPS 
7-bit code. 


Fixed-Length Records 


The size of fixed-length (format-F) records, shown in Figure 3, is constant for all 
records in the data set. The number of records within a block is constant for 
every block in the data set, unless the data set contains truncated (short) blocks. 
If the data set contains unblocked format-F records, one record constitutes one 
block. 

The system automatically performs physical length checking (except for card 
readers) on blocked or unblocked format-F records. Allowances are made for 
truncated blocks. 

Format-F records are shown in Figure 3. The optional control character (a), 
used for stacker selection or carriage control, may be included in each record to 
be printed or punched. 
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Figure 3. Fixed-Length Records 


Fixed-Length Records, Standard Format 

During creation of a sequential data set (to be processed by BSAM or QSAM) 
with fixed-length records, the RECFM subparameter of the DCB macro 
instruction may specify a standard format (RECFM = FS or FBS). A 
standard-format data set must conform to the following specifications: 
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• All records in the data set are format-F records. 

• No block except the last block is truncated. (With BSAM, you must ensure 
that this specification is met.) 

• Every track except the last contains the same number of blocks. 

• Every track except the last is filled to capacity as determined by the track 
capacity formula established for the device. (These formulas are presented in 
Appendix C, “Allocating Space on Direct Access Volumes” on page 217.) 

• The data set organization is physical sequential. A member of a partitioned 
data set cannot be specified. 

A sequential data set with fixed-length records having a standard format can be 
read more efficiently than a data set that doesn't specify a standard format. This 
efficiency is possible because the system is able to determine the address of each 
record to be read, because each track contains the same number of blocks. 

You should never extend a standard-format data set (by coding DISP= MOD) if 
the last block is truncated, because the extension will cause the data set to 
contain a truncated block that isn't the last block. Reading an extended data set 
with this condition will result in a premature end of data condition when the 
truncated block is read, giving the appearance that the blocks following this 
truncated block do not exist. This type of data set on magnetic tape should not 
be read backward, because the data set would begin with a truncated block, 
Consequently, you probably won't want to use this type of data set with 
magnetic tape. If you use one of the basic access techniques with this type of 
data set, you should not use the track overflow feature. 

Standard format should not be used to read records from a data set that was 
created using a RECFM other than standard, because other record formats may 
not create the precise format required by standard. 

If at any time the characteristics of your data set are altered from the 
specifications described above, the data set should no longer be processed with 
the standard format specification. 


Fixed-Length Records, ISO/ANSI/FIPS Tapes 

For ISO/ANSI/FIPS tapes, format-F records are the same as described above, 
with three exceptions: 

• Control characters, if present, must be ISO/ANSI/FIPS control characters. 
For more information about control characters, see Appendix B, “Control 
Characters” on page 213. 

• Record blocks can contain block prefixes. 

The block prefix can vary from 0 to 99 bytes, but the length must be 
constant for the data set being processed. For blocked records, the block 
prefix precedes the first logical record. For unblocked records, the block 
prefix precedes each logical record. 
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Using QSAM and BSAM to read records with block prefixes requires that 
you specify the BUFOFF operand in the DCB. When using QSAM, you do 
not have access to the block prefix on input. When using BSAM, you must 
account for the block prefix on both input and output. When using either 
QSAM or BSAM, you must account for the length of the block prefix in the 
BLKSIZE and BUFL operands of the DCB. 

When using QSAM to output DB or DBS records and BUFOFF = 0 is 
specified, the value of the BUFL operand, if specified, must be increased by 
4. If BUFL is not specified, then the BLKSIZE operand must be increased 
by 4. This allows for a 4-byte QSAM internal processing area to be included 
when the system acquires the buffers. These 4 bytes will not become part of 
the user's block. 

When you use BSAM on output records, the operating system does not 
recognize a block prefix. Therefore, if you want a block prefix, it must be 
part of your record. Note that you cannot include block prefixes in QSAM 
output records. 

The block prefix, as for all the data records for ISO/ANSI/FIPS tapes, can 
only contain EBCDIC characters that correspond to the 128, seven-bit 
ASCII characters. Thus, you must avoid using data types such as binary, 
packed decimal, and floating point that cannot always be translated into 
ISCII/ASCII. (See the Note in Chapter 3, “Record Formats” on page 13.) 

Figure 4 on page 17 shows the format of fixed-length records for 
ISO/ANSI/FIPS tapes and where control characters and block prefixes are 
positioned if they exist. 

• The GET routine tests each record (except the first) for all circumflex 

characters (X'5E'). If a record completely filled with circumflex characters is 
detected, the end-of-block (EOB) routine is called to get the next block. A 
fixed-length record must not consist of only circumflex characters. This 
restriction is necessary because circumflex characters are used to pad out a 
block of records when fewer than the maximum number of records are 
included in a block, and the block is not truncated. 
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Figure 4. Fixed-Length Records for ISO/ANSI/FIPS Tapes 


Variable-Length Records 

The variable-length record formats are format-V and format-D. They can also be 
spanned (format-VS or -DS), blocked (format-VB or -DB), or both (format-VBS 
and -DBS). Format-D, -DS, and -DBS records are used for ISO/ANSI/FIPS 
tape data sets. Figure 5 on page 18 shows blocked and unblocked 
variable-length (format-V) records without spanning. 
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Figure 5. Nonspanned, Format-V Records 


Variable-Length Records—Format-V 

Format V provides for variable-length records and variable-length record 
segments, each of which describes its own characteristics, and for variable-length 
blocks of such records or record segments. Except when variable-length track 
overflow records are specified for volumes on devices with the rotational position 
sensing feature, the control program performs length checking of the block and 
uses the record or segment length information in blocking and unblocking. The 
first 4 bytes of each record, record segment, or block make up a descriptor word 
containing control information. You must allow for these additional 4 bytes in 
both your input and output buffers. 

Block Descriptor Word: A variable-length block consists of a block descriptor 
word (BDW) followed by one or more logical records or record segments. The 
block descriptor word is a 4-byte field that describes the block. The first 2 bytes 
specify the block length LL—4 bytes for the BDW plus the total length of all 
records or segments within the block. This length can be from 8 to 32760 bytes 
or, when you are using WRITE with tape, from 18 to 32760. The third and 
fourth bytes are reserved for possible future system use and must be 0. If the 
system does your blocking—that is, when you use the queued access 
technique—the operating system automatically provides the BDW when it writes 
the data set. If you do your own blocking—that is, when you use the basic access 
technique—you must supply the BDW. 
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Record Descriptor Word: A variable-length logical record consists of a record 
descriptor word (RDW) followed by the data. The record descriptor word is a 
4-byte field describing the record. The first 2 bytes contain the length LL of the 
logical record (including the 4-byte RDW). The length can be from 4 to 32756. 
All bits of the third and fourth bytes must be 0, because other values are used for 
spanned records. For output, you must provide the RDW except in data mode 
for spanned records (described under “Buffer Control” on page 123). For output 
in data mode, you must provide the total data length in the physical record length 
field (DCBPRECL) of the DCB. For input, the operating system provides the 
RDW except in data mode. In data mode, the system passes the record length to 
your program in the logical record length field (DCBLRECL) of the DCB. The 
optional control character (a) may'be specified as the fifth byte of each record 
and must be followed by at least one byte of data (the length in the RDW, in this 
case, would be 6). The first byte of data is a table reference character if 
OPTCD = J has been specified. The RDW, the optional control character, and 
the optional table reference character are not punched or printed. 

Spanned Format-VS Records (Sequential Access Method) 

Figure 6 on page 20 shows how the spanning feature of the queued and basic 
sequential access methods lets you create and process variable-length logical 
records that are larger than one physical block and/or to pack blocks with 
variable-length records by splitting the records into segments so that they can be 
written into more than one block. 

When spanning is specified for blocked records, the system tries to fill all blocks. 
For unblocked records, a record larger than block size is split and written in two 
or more blocks, each block containing only one record or record segment. Thus 
the block size may be set to the one that is best for a given device or processing 
situation. It is not restricted by the maximum record length of a data set. A 
record may, therefore, span several blocks, and may even span volumes. Note 
that a logical record spanning three or more volumes cannot be processed in 
update mode (described under “Buffer Control” on page 123) by QSAM. For 
blocked records, a block can contain a combination of records and record 
segments, but not multiple segments of the same record. When records are added 
to or deleted from a data set, or when the data set is processed again with 
different block size or record size parameters, the record segmenting will change. 
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Figure 6. Spanned Format-VS Records (Sequential Access Method) 


Considerations for Processing Spanned Record Data Sets 

When spanned records span volumes, reading errors may occur when using 
QSAM if a volume that begins with a middle or last segment is mounted first or 
if an FEOV macro instruction is issued followed by another GET. QSAM 
cannot begin reading from the middle of the record. The errors include duplicate 
records, program checks in the user's program, and invalid input from the 
spanned record data set. 

When QSAM opens a spanned record data set in UPDAT mode, it uses logical 
record interface (LRI) to assemble all segments of the spanned record into a 
single, logical input record and to disassemble a single logical record into multiple 
segments for output data blocks. A record area must be provided by using the 
BUILDRCD macro instruction or by specifying BFTEK = A in the DCB. 

Note: When you specify BFTEK = A, the Open routine provides a record area 
equal to the LRECL specification, which should be the maximum length in 
bytes. (An LRECL= 0 is invalid.) 

If you issue the FEOV macro when reading a data set that spans volumes, or if a 
spanned multivolume data set is opened to other than the first volume, make sure 
that each volume begins with the first (or only) segment of a logical record. 

Input routines cannot begin reading in the middle of a logical record. 
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Segment Descriptor Word: Each record segment consists of a segment descriptor 
word (SDW) followed by the data. The segment descriptor word, similar to the 
record descriptor word, is a 4-byte field that describes the segment. The first 2 
bytes contain the length LL of the segment, including the 4-byte SDW. The 
length can be from 5 to 32756 bytes or, when you are using WRITE with tape, 
from 18 to 32756 bytes. The third byte of the SDW contains the segment control 
code that specifies the relative position of the segment in the logical record. The 
segment control code is in the rightmost 2 bits of the byte. The segment control 
codes are shown in Figure 7. The remaining bits of the third byte and all of the 
fourth byte are reserved for possible future system use and must be 0. 


Binary 

Code 

00 

01 

10 

11 

Figure 7. 


Relative Position of Segment 
Complete logical record 
First segment of a multisegment record 
Last segment of a multisegment record 

Segment of a multisegment record other than the first or last segment 
Segment Control Codes 


The SDW for the first segment replaces the RDW for the record after the record 
has been segmented. You or the operating system can build the SDW, depending 
on which access method is used. In the basic sequential access method, you 
must create and interpret the spanned records yourself. In the queued sequential 
access method move mode, complete logical records, including the RDW, are 
processed in your work area. GET consolidates segments into logical records and 
creates the RDW. PUT forms segments as required and creates the SDW for 
each segment. Data mode is similar to move mode, but allows reference only to 
the data portion of the logical record (that is, to one segment) in your work area. 
The logical record length is passed to you through the DCBLRECL field of the 
data control block. In locate mode, both GET and PUT process one segment at 
a time. However, in locate mode, if you provide your own record area using the 
BUILDRCD macro or if you ask the system to provide a record area by 
specifying BFTEK = A, then GET, PUT, and PUTX process one logici record 
at a time. (BFTEK = A or the BUILDRCD macro cannot be specified when 
logical records exceed 32760 bytes. To process logical records that exceed 32760 
bytes, you must use locate mode and specify LRECL= X in your DCB macro.) 

A logical record spanning three or more volumes cannot be processed when the 
data set is opened for update. 

When unit record devices are used with spanned records, the system assumes that 
unblocked records are being processed and the block size must be equivalent to 
the length of one print line or one card. Records that span blocks are written 
one segment at a time. 

Note: Spanned variable-length records cannot be specified for a SYSIN data set. 
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Null Segments 


A 1 in bit position 0 of the SDW indicates a null segment. A null segment 
means that there are no more segments in the block. Bits 1 to 7 of the SDW and 
the remainder of the block must be binary zeros. A null segment is not an 
end-of-logical-record delimiter. (You do not have to be concerned about null 
segments unless you have created a data set using null segments.) 

Spanned Variable-Length Records (Basic Direct Access Method) 

The spanning feature of the basic direct access method (BDAM) lets you create 
and process variable-length unblocked logical records that span tracks. The 
feature also lets you pack tracks with variable-length records by splitting the 
records into segments. Figure 8 shows how these segments can then be written 
onto more than one track. 


Track 1 


Track 2 


Track 3 


Block 



LL 


BOW 


Data Portion of Logical Record A 


Logical Record 
(In User's Work 
Area) 

Block Length - 
2 Bytes 

Reserved 
2 Bytes 



Figure 8. Spanned Format-V Records for BDAM Data Sets 


When you specify spanned, unblocked record format for the basic direct access 
method and when a complete logical record cannot fit on the track, the system 
tries to fill the track with a record segment. Thus the maximum record length of 
a data set is not restricted by track capacity. Furthermore, segmenting records 
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allows a record to span several tracks, with each segment of the record on a 
different track. However, because the system does not allow a record to span 
volumes, all segments of a logical record in a direct data set are on the same 
volume. 

ISO/ANSI/FIPS Variable-Length Records-Format D 

For ISO/ANSI/FIPS tapes, nonspanned variable-length records are format-D 
records. ISO/ANSI/FIPS records are the same as format-V records, with the 
following exceptions: 

♦ Block prefix—A record block can contain a block prefix. To specify a block 

prefix, code the BUFOFF operand in the DCB macro. The block prefix can 
vary in length from 0 to 99 bytes but its length must remain constant for all 
records in the data set being processed. For blocked records, the block prefix 
precedes the RDW for first or only logical record in each block. For 
unblocked records, the block prefix precedes the RDW for each logical 
record. 

To specify that the block prefix is to be treated as a BDW by data 
management for format-D or -DS records on output, code BUFOFF = L as 
a DCB operand. Your block prefix must be 4 bytes long, and it must 
contain the length of the block, including the block prefix. The maximum 
length of a format-D or -DS, BUFOFF = L block is 9999, because the length 
(stated in binary by the user) is translated to a 4-byte ASCII character 
decimal field on the ISO/ANSI/FIPS tape when the block is written. It is 
converted back to a 2-byte length field in binary followed by two bytes of 
zeros when the block is read. If you use QSAM to write records, data 
management fills in the block prefix for you. If you use BSAM to write 
records, you must fill in the block prefix yourself. If you are using chained 
scheduling to read blocked DB or DBS records, you cannot code 
BUFOFF = absolute expression in the DCB. Instead, BUFOFF = L is 
required, because the access method needs binary RDWs and valid block 
lengths to unblock the records. 

When you use QSAM, you cannot read the block prefix into your record 
area on input. When using BSAM, you must account for the block prefix on 
both input and output. When using either QSAM or BSAM, you must 
account for the length of the block prefix in the BLKSIZE and BUFL 
operands. 

When you use BSAM on output records, the operating system does not 
recognize the block prefix. Therefore, if you want a block prefix, it must be 
part of your record. 

The block prefix can only contain EBCDIC characters that correspond to the 
128, seven-bit ASCII characters. Thus, you must avoid using data types, such 
as binary, packed decimal, and floating point, that cannot always be 
translated into ISCII/ASCII. (See the Note in Chapter 3, “Record 
Formats” on page 13.) For DB and DBS records, the only time the block 
prefix can contain binary data is when you have coded BUFOFF = L, which 
tells data management that the prefix is a BDW. Unlike the block prefix, the 
RDW must always be in binary. 
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• Block size —Version 3 tapes have a maximum block size of 2048. This limit 
may be overridden by a label validation installation exit. 

If you create variable-length blocks that are shorter than 18 bytes, data 
management pads each one to 18 bytes when the blocks are written onto an 
ISO/ANSI/FIPS tape. The padding character used is the ISCII/ASCII 
circumflex character. 

• Control characters— Control characters, if present, must be ISO/ANSI control 
characters. For more information about control characters, see 
Appendix B, “Control Characters” on page 213. 

Figure 9 shows the format of nonspanned variable-length records for 
ISO/ANSI/FIPS tapes, where the record descriptor word (RDW) is located, and 
where block prefixes and control characters must be placed when they are used. 
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Note: Block prefixes on output records must be 4-bytes long. 

Figure 9. Nonspanned Form at-D Records for ISO/ANSI/FIPS Tapes 


ISO/ANSI/FIPS Variable-Length Spanned Records-Format-DS or Format-DBS 

For ISO/ANSI/FIPS tapes, variable-length spanned records must be specified in 
the DGB RECFM parameter as DCB RECFM = DS or DBS. Format-DS and 
-DBS records are similar to format-VS or -VBS records with the following 
exceptions: 

• Segment descriptor word (SDW )—There is an additional byte preceding each 

SDW for DS/DBS records. This additional byte is required for conversion of ( f \ 

the SDW from IBM to ISO/ANSI/FIPS format, because the ISO/ANSI 4 y 

SDW (called a segment control word) is five bytes long. Otherwise, the SDW 
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for DS/DBS records is the same as the SDW for VS/VBS records. The 
SDW LL count excludes the additional byte. (See “Processing Considerations 
for DS and DBS Records” on page 25.) 

• Extended logical record interface (XLRl)— DS/DBS records may be 
processed using XLRI. (See “Processing Considerations for DS and DBS 
Records.”) 

• The exceptions previously noted (“ISO/ANSI/FIPS Variable-Length 
Records—Format D” on page 23) for format-D records still apply. 

Figure 10 on page 26 shows what spanned variable-length records for 
ISO/ANSI/FIPS tapes look like when you are using IBM access methods. The 
figure shows the segment descriptor word (SDW), where the record descriptor 
word (RDW) is located, and where block prefixes must be placed when they are 
used. If you are not using IBM access methods, see 

Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 
Word” on page 223, for a description of ISO/ANSI/FIPS record control words 
and segment control words. 

Processing Considerations for DS and DBS Records 

When using QSAM, the same application used to process VS/VBS tape files can 
be used to process DS/DBS tape files. However, you must ensure that 
ISO/ANSI/FIPS requirements such as block size limitation, tape device, and 
restriction to EBCDIC characters that correspond to the 128, seven-bit ASCII 
characters are met. The SCW/SDW conversion and buffer positioning is handled 
by the GET/PUT routines. 

When using BSAM to process a DS/DBS tape file, you must allow for an 
additional byte at the beginning of each SDW. The SDW LL must exclude the 
additional byte. On input, you must ignore the unused byte preceding each SDW. 
On output, you must allocate the additional byte for each SDW. 

SDW Conversion: Sequential access method end-of-block (EOB) routines 
perform conversion between ISO/ANSI/FIPS segment control word (SCW) 
format and IBM segment descriptor word (SDW) format for both QSAM and 
BSAM processing. On output, the binary SDW LL value (provided by you 
when using BSAM and by the access method when using QSAM), is increased 
by 1 for the extra byte and converted to four ISO/ANSI/FIPS numeric 
characters. Because the binary SDW LL value will result in four numeric 
characters, the binary value must not be greater than 9998. The fifth character is 
used to designate which segment type (complete logical record, first segment, last 
segment, or intermediate segment) is being processed. 

On input, the four numeric characters designating the segment length are 
converted to two binary SDW LL bytes and decreased by one for the unused 
byte. The ISO/ANSI/FIPS segment control character maps to the DS/DBS 
SDW control flags. This conversion leaves an unused byte at the beginning of 
each SDW. It is set to X'00'. For more detail on this process, see 
Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 
Word” on page 223. 
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XLRI Mode: The extended logical record interface (XLRI) may be used with 
DS/DBS files to communicate LRECL values over 32760. (XLRI is supported 
only in QSAM locate mode for ISO/ANSI/FIPS tapes.) XLRI should be used 
for any case where the logical record will exceed 32760 bytes. Using the 
LRECL = X for ISO/ANSI/FIPS causes an 013-DC abend. 

To use XLRI, specify LRECL^ OK or LRECL = nK in the DCB macro. 
Specifying DCBLRECL with the K suffix sets the DCBBFTK bit that indicates 
that LRECL is coded in K units and that the DCB is to be processed in XLRI 
mode. 

LRECL = OK in the DCB macro specifies that the LRECL value will come from 
the file label or JCL. When LRECL is from the label, the file must be opened as 
an input file. The label (HDR2) value for LRECL will be converted to kilobytes 
and rounded up when XLRI is in effect. When the ISO/ANSI/FIPS label value 
for LRECL is 00000 to show that the maximum record length may be greater 
than 99999, the LRECL = nK must be used in the JCL or in the DCB to specify 
the maximum record length. 

The LRECL from JCL can be expressed in absolute form or with the K 
notation. Absolute values, permissible only from 5 to 32760, will be converted to 
kilobytes by rounding up to an integral multiple of 1024 when the DCB is for 
XLRI. 

To show the record area size in the DD statement, code DCB = LRECL = nK. 
The value nK may range from IK to 16383K (expressed in 1024-byte multiples). 
However, depending on the buffer space available, the value you can specify in 
most systems will be much smaller than 16383K bytes. This value is used to 
determine the size of the record area required to contain the largest logical record 
of the spanned format file. 

When using XLRI, the exact LRECL size is communicated in the three 
low-order bytes of the RDW in the record area. This special RDW format exists 
only in the record area to communicate the length of the logical record (including 
the 4-byte RDW) to be written or read. (See the XLRI format of the RDW in 
Figure 10 on page 26.) DCB LRECL shows the 1024-multiple size of the 
record area (rounded up to the next nearest kilobyte). The normal DS/DBS 
SDW format is used at all other times before conversion. 


Undefined-Length Records 

Format-U permits processing of records that do not conform to the F or V 
format. Figure 11 on page 28 shows how each block is treated as a record; 
therefore, any unblocking that is required must be performed by your program. 
The optional control character may be used in the first byte of each record. 
Because the system does not do length checking on format-U records, your 
program may be designed to read less than a complete block into virtual storage. 
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Figure 11. Undefined-Length Records 


For format-U records, the user must specify the record length when issuing the 
WRITE, PUT, or PUTX macro instruction. No length checking is performed 
by the system, so no error indication will be given if the specified length does not 
match the buffer size or physical record size. 

In update mode, you must issue a GET or READ macro before you issue a 
PUTX or WRITE macro to a data set on a direct access device. If you change 
the record length when you issue the PUTX or WRITE macro, the record will 
be padded with zeros or truncated to match the length of the record received 
when the GET or READ macro was issued. No error indication will be given. 

For Version 3 ISO/ANSI/FIPS tapes, format-U records are not supported. An 
attempt to process a format-U record from a Version 3 tape will result in entering 
the label validation installation exit. 

ISO/ANSI Version 1 (ISO 1001-1969 and ANSI X3.27-1969) tapes containing 
format-U records can be used for input only. These records are the same as the 
format-U records described above, except the control characters must be 
ISO/ANSI control characters, and block prefixes can be used. 


Record Format—Device Type Considerations 

Before executing your program, you must supply the operating system with the 
record format (RECFM) and device-dependent information in a DCB macro 
instruction, a DD statement, or a data set label. The DCB subparameters for the 
DD statement differ slightly from those described here. A complete description 
of the DD statement and a glossary of DCB subparameters are contained in JCL. 

The record format (RECFM) parameter of the DCB macro specifies the 
characteristics of the records in the data set as fixed-length (RECFM = F), 
variable-length (RECFM = V or D), variable-spanned (RECFM = DS or -VS), or 
undefined-length (RECFM = U). All record formats except U can be blocked. 
Fixed-length blocked records (RECFM = FB) can be specified as standard 
(RECFM = FBS), meaning that there are no truncated (short) blocks or unfilled 
tracks within the data set, with the possible exception of the last block or track. 
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Data sets with a fixed-length, standard format are described under “Fixed-Length 
Records, Standard Format” on page 14. 

As an optional feature, a control character can be contained in each record. This 
control character will be recognized and processed if the data set is printed or 
punched. The control characters are transmitted on both tapes and direct access 
volumes. The presence of a control character is indicated by M or A in the 
RECFM field of the data control block. M denotes machine code; A denotes 
American National Standards Institute (ANSI) code. If either M or A is 
specified, the character must be present in every record; the printer space 
(PRTSP) or stacker select (STACK) field of the DCB is ignored. The optional 
control character must be in the first byte of format-F and format-U records and 
in the fifth byte of format-V records and format-D records where BUFOFF = L. 
Control character codes are listed in Appendix B, “Control Characters” on 
page 213. The device-dependent (DEVD) parameter of the DCB macro specifies 
the type of device where the data set's volume resides: 

• TA magnetic tape 

• PR printer 

• PC card punch 

• RD card reader 

• DA direct access device or Mass Storage System (MSS) virtual volumes 

Note: Because the DEVD option is required only for the DCB macro 
expansion, you are guaranteed the maximum device flexibility by letting it default 
to DEVD = DA. 


Magnetic Tape 


Format-F, -V, -D, and -U records are acceptable for magnetic tape. Format-V 
records are not acceptable on 7-track tape if the data conversion feature is not 
available. ASCII records are not acceptable on 7-track tape. 

When you create a tape data set with variable-length record format-V or -D, the 
control program pads any data block shorter than 18 bytes. For format-V 
records, it pads to the right with binary zeros so that the data block length equals 
18 bytes. For format-D (ASCII) records, the padding consists of ASCII 
circumflex characters, which are equivalent to X'5E's. 

Note that there is no minimum requirement for block size. However, in 
nonretum-to-zero-inverted mode, if a data check occurs on a magnetic tape 
device, any record shorter than 12 bytes in a read operation will be treated as a 
noise record and lost. No check for noise will be made unless a data check 
occurs. 

Figure 12 on page 30 shows how the tape density (DEN) specifies the recording 
density in bits per inch per track. When DEN is not specified, the highest density 
capable by the unit will be used. 
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Recording Density 


DEN 7-Track Tape 9-Track Tape 
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1 
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3 
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556 (NRZI) 

N/A 

N/A 

800 (NRZI) 

800 (NRZI) 1 

N/A 

N/A 

1600 (PE) 2 

N/A 

N/A 

6250 (GCR) 3 

N/A 


Notes: 


NRZI is for nonretum-to-zero-inverted mode. 


PE is for phase encoded mode. 

GCR is for group coded recording mode. 


Figure 12. Tape Density (DEN) Values 


The track recording technique (TRTCH) for 7-track tape can be specified as: 

C 

Data conversion is to be used. Data conversion makes it possible to write 
8 binary bits of data on 7 tracks. Otherwise, only 6 bits of an 8-bit byte are 
recorded. The length field of format-V records contains binary data and is 
not recorded correctly without data conversion. 

E 

Even parity is to be used; if E is omitted, odd parity is assumed. 

T 

BCDIC to EBCDIC translation is required. 

Card Reader and Punch 

Format-F and -U records are acceptable to both the reader and the punch; 
format-V records are acceptable to the punch only. The device control character, 
if specified in the RECFM parameter, is used to select the stacker; it is not 
punched. The first 4 bytes (record descriptor word or segment descriptor word) of 
format-V records or record segments are not punched. For format-V records, at 
least 1 byte of data must follow the record or segment descriptor word or the 
carriage control character. 

Each punched card corresponds to one physical record. Therefore, you should 
restrict the maximum record size to 80 (EBCDIC mode) or 160 (column binary 
mode) data bytes. When mode (C) is used for the card punch, BLKSIZE must 
be 160 unless you are using PUT. Then you can specify BLKSIZE as 160 or a 
multiple of 160, and the system handles this as described under “PUT—Write a 
Record” on page 66. You can specify the read/punch mode of operation 
(MODE) parameter as either card image (column binary) mode (C) or EBCDIC 
mode (E). If this information is omitted, E is assumed. The stacker selection 
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parameter (STACK) can be specified as either 1 or 2 to show which bin is to 
receive the card. If it is not specified, 1 is assumed. 

For all QSAM, RECFM = FB, card punch data sets, the block size in the DCB 
will be adjusted by the system to equal the logical record length. This data set 
will be treated as RECFM = F. If the system builds the buffers for this data set, 
the buffer length will be determined by the BUFL parameter. If the BUFL 
parameter was not specified, the adjusted block size is used for the buffer length. 

If the DCB is to be reused with a block size larger than the logical record length, 
you must reset DCBBLKSI in the DCB and ensure that the buffers are large 
enough to contain the largest block size expected. You may ensure the buffer 
size by specifying the BUFL parameter before the first time the data set is opened 
or by issuing the FREEPOOL macro after each CLOSE macro so the system 
will build a new buffer pool of the correct size each time the data set is opened. 

Punch error correction on the IBM 2540 Card Read Punch is not performed. 

The IBM 3525 Card Punch accepts only format-F records for print data sets and 
for associated data sets. Other record formats are allowed for the read data set, 
the punch data set, and the interpret punch data set. For more information on 
programming for the 3525 Card Punch, see OS and OSjVS Programming Support 
for the IBM 3505 Card Reader and IBM 3525 Card Punch . 


Printer 


With the IBM 3800 Printing Subsystem, the data in the record can contain two 
optional bytes—the optional control character used for carriage control, followed 
by an optional table reference character used for dynamically selecting a character 
arrangement table during printing. These characters are discussed below. 

Carriage Control Character 

You may specify in the DD statement, the DCB macro, or the data set label that 
an optional control character is part of each record in the data set. The Lbyte 
character is used to show a carriage control function when the data set is printed 
or a stacker bin when the data set is punched. Although the character is a part of 
the record in storage, it is never printed or punched. Note that buffer areas must 
be large enough to accommodate the character. If the immediate destination of 
the record is a device, such as a disk, that does not recognize the control 
character, the system assumes that the control character is the first byte of the 
data portion of the record. If the destination of the record is a printer or punch 
and you have not indicated the presence of a control character, the system regards 
the control character as the first byte of data. A list of the control characters is in 
Appendix B, “Control Characters’' on page 213. 
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3800 Table Reference Character 


The 3800 table reference character is a numeric character (0, 1, 2, or 3) 
corresponding to the order in which the character arrangement table names have 
been specified with the CHARS keyword. It is used for selection of a character 
arrangement table during printing. (For more information on the table reference 
character, see IBM 3800 Printing Subsystem Programmer's Guide.) 

A numeric table reference character (such as 0) selects from within the table that 
font to which the character corresponds. The characters' number values represent 
the order in which the font names have been specified with the CHARS 
parameter. In addition to using table reference characters to correspond to font 
names specified on the CHARS parameter, you can also code table reference 
characters that correspond to font names specified in PAGEDEF control 
structure. Valid table reference characters vary and range between 0 and 126. 
Table reference characters with values greater than 126 default to a value of 0 
(zero). For additional information, see IBM 3800 Printing Subsystem 
Programmer's Guide . 


Record Formats 


Records of format-F, -V, and -U are acceptable to the printer. The first 4 bytes 
(record descriptor word or segment descriptor word) of format-V records or 
record segments are not printed. For format-V records, at least 1 byte of data 
must follow the record or segment descriptor word or the carriage control 
character. The carriage control character, if specified in the RECFM parameter, is 
not printed. The system does not position the printer to channel 1 for the first 
record unless specified by a carriage control character. 

Because each line of print corresponds to one record, the record length should 
not exceed the length of one line on the printer. For variable-length spanned 
records, each line corresponds to one record segment, and block size should not 
exceed the length of one line on the printer. 

If carriage control characters are not specified, you can show printer spacing 
(PRTSP) as 0, 1, 2, or 3. If it is not specified, 1 is'assumed. 

For all QSAM, RECFM = FB, printer data sets, the block size in the DCB will 
be adjusted by the system to equal the logical record length. This data set will be 
treated as RECFM = F. If the system builds the buffers for this data set, the 
buffer length will be determined by the BUFL parameter. If the BUFL 
parameter was not specified, the adjusted block size is used for the buffer length. 

If the DCB is to be reused with a block size larger than the logical record length, 
you must reset DCBBLKSI in the DCB and ensure that the buffers are large 
enough to contain the largest block size expected. You may ensure the buffer 
size by specifying the BUFL parameter before the first time the data set is opened 
or by issuing the FREEPOOL macro after each CLOSE macro so the system 
will build a new buffer pool of the correct size each time the data set is opened. 
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Direct Access Device 


Direct access devices accept records of format-F, -V, or -U. If the records are to 
be read or written with keys, the key length (KEYLEN) must be specified. In 
addition, the operating system has a standard track format for all direct access 
volumes. Each track contains data information and certain control information 
such as: 

♦ The address of the track 

• The address of each record 

♦ The length of each record 

• Gaps between areas 

A complete description of track format is contained in “Direct Access Volumes” 
on page 5. 
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Chapter 4. Selecting an Access Method 


The operating system allows you to concentrate most of your efforts on 
processing the records read or written by the data management routines. To get 
the records read and written, your main responsibility is to describe the data set 
to be processed, the buffering techniques to be used, and the access method. An 
access method has been defined as the combination of data set organization and 
the technique (queued or basic) used to gain access to the data. 


Overview of Access Methods 

Access methods are identified primarily by the data set organization to which 
they apply. For instance, BDAM is the basic access method for direct 
organization. Nevertheless, there are times when an access method identified 
with one organization can be used to process a data set usually thought of as 
organized in a different manner. Thus, a data set created by the basic access 
method for sequential organization (BSAM) may be processed by the basic direct 
access method (BDAM) and visa versa. If the queued access technique is used to 
process a sequential data set, the access method is called the queued sequential 
access method (QSAM). 

Basic access methods are used for all data organizations, while queued access 
methods apply only to sequential and indexed sequential data sets as shown in 
Figure 13. 


Data Set 

Access Technique 

Organization 

Basic 

Queued 

Sequential 

BSAM 

QSAM 

Partitioned 

BPAM 


Indexed Sequential 

BISAM 

QISAM 

Direct 

BDAM 



Figure 13. Data Management Access Methods 


It is possible to control an I/O device directly while processing a data set with 
any data organization without using a specific access method. The execute 
channel program (EXCP) macro instruction uses the system programs that 
provide for scheduling and queuing I/O requests, efficient use of channels and 
devices, data protection, interruption procedures, error recognition, and retry. 
Complete details about the EXCP macro are in System-Data Administration. 
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Temporary data sets can be handled by a function called virtual I/O (VIO). Data 
sets for which VIO is specified are located in external page storage. However, to 
the access methods (BDAM, BPAM, BSAM, QSAM, and EXCP), the data sets 
appear to reside on a real direct access storage device. VIO provides these 
advantages: 

• Elimination of some of the usual I/O device allocation and data management 
overhead for temporary data sets 

• Generally more efficient use of direct access storage space 

To use VIO, you must specify VIO = YES in the UNITNAME macro during 
system generation, and you must specify a unitname (defined in the 
UNITNAME macro) on the DD statement for your data set. For additional 
information on VIO, see Initialization and Tuning Guide. For information on the 
UNITNAME macro, see System Generation Reference. For information on 
changes to the DD statement, see JCL. 


Basic Direct Access Method (BDAM) 

Before you use the BDAM access method to process a data set, consider these 
implications: 

• You create a BDAM data set with the basic sequential access method 
(BSAM). A special operand in the BSAM DCB macro (MACRF = WL) 
shows that you want to create a BDAM data set. 

• The problem program must synchronize all I/O operations with a CHECK 
or a WAIT macro. 

• The problem program must block and unblock its own input and output 
records. (BDAM only reads and writes data blocks.) 

• You can find data blocks within a data set with one of the following 
addressing techniques: 

— Actual device addresses. 

— Relative track address technique. This locates a track on a direct access 
device relative to the beginning of the data set. 

— Relative block address technique. This locates a fixed-length data block 
relative to the beginning of the data set. 

For more information about coding the DCB macro to process a BDAM data 
set, see Data Administration: Macro Instruction Reference. 
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Basic Indexed Sequential Access Method (BISAM) 


Before you use the BISAM access method to process an ISAM data set, consider 
these implications: 

• BISAM accesses only ISAM data sets. 

• BISAM cannot be used to create an indexed sequential access method 
(ISAM) data set. 

• BISAM directly retrieves logical records by key, updates blocks of records 
in-place, and inserts new records in their correct key sequence. 

• The problem program must synchronize all I/O operations with a CHECK 
or a WAIT macro. 

• Other DCB operands are available to reduce input/output operations by 
defining work areas that contain the highest level master index and the 
records being processed. 

For more information about coding the DCB macro to process a BISAM data 
set, see Data Administration: Macro Instruction Reference . 

Basic Partitioned Access Method (BPAM) 

BPAM is a subset of BSAM, which processes only the directory of a partitioned 
data set. BSAM processes the data set members. 

Before you use the BPAM access method to process a data set, consider these 
implications: 

• One complete partitioned data set must be on one direct-access volume, but 
you can concatenate multiple input data sets that are on the same or different 
volumes. 

• When you create a partitioned data set, you must specify the SPACE 
parameter on your first (or only) DD statement for the data set. This 
parameter defines the size of the data set and its directory so that the system 
can allocate data set space and pre-format the directory. 

• You can use either the basic sequential access method (BSAM) or the 
queued sequential access method (QSAM) to add or retrieve a BPAM data 
set member without specifying the BLDL, FIND, or the STOW macro by 
coding the DSORG = PS operand in the DCB macro. (Data set positioning 
and directory maintenance are then handled by the OPEN and CLOSE 
macros.) But, be advised that you are really processing the member as if it 
were part of a sequential data set, so you are not using the complete 
capabilities of BPAM. 

• You can use the STOW macro to add, delete, change, or replace an element 
name or alias in the directory. 
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• You can process multiple data set members by passing a list of members to 
BLDL. Then you can use the FIND macro to position to a member before 
processing it. 

For more information about coding the DCB macro to process a BPAM data 
set, see Data Administration: Macro Instruction Reference. 

Basic Sequential Access Method (BSAM) 

Before you use the BSAM access method to process a data set, consider these 
implications: 

• The problem program must block and unblock its own input and output 
records. (BSAM only reads and writes data blocks.) 

• The problem program must manage its own input and output buffers. It 
must give BSAM a buffer address with the READ macro, and it must fill its 
own output buffer before issuing the WRITE macro. 

• The problem program must synchronize its own I/O operations by issuing a 
CHECK macro for each READ and WRITE macro issued. 

• BSAM lets you process nonsequential blocks by repositioning with the 
NOTE and POINT macros. 

• You can read and write direct access device record keys with BSAM. 

For more information about coding the DCB macro to process a BSAM data 
set, see Data Administration: Macro Instruction Reference . 

Queued Indexed Sequential Access Method (QISAM) 

Before you use the QISAM access method to process an ISAM data set, consider 
these implications: 

• The characteristics of a QISAM data set are established when the data set is 
created. You can't change them without reorganizing the data set. The 
DCB operands that establish these characteristics are: BLKSIZE, CYLOFL, 
KEYLEN, LRECL, NTM, OPTCD, RECFM, and RKP. 

• A QISAM data set can consist of unblocked fixed-length records (F), blocked 
fixed-length records (FB), unblocked variable-length records (V), or blocked 
variable-length records (VB). 

• QISAM can create an indexed sequential data set (QISAM, load mode), add 
additional data records at the end of the existing data set (QISAM, resume 
load mode), update a record in place, or retrieve records sequentially 
(QISAM, scan mode). 

• You can't use track overflow to create or extend an ISAM data set. 
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• When you create an indexed sequential data set, you can allocate space for 
the data set's prime area, overflow area, and its cylinder/master index(es) on 
the same or separate volumes. For more information about space allocation, 
see JCL . 

• QISAM automatically generates a track index for each cylinder in the data set 
and one cylinder index for the entire data set. Specify the DCB operands 

M M and OPTCD to show that the data set requires a master index(es). 
QISAM creates and maintains as many as three levels of master indexes. 

• You can purge records by specifying the OPTCD = L DCB option when you 
create an ISAM data set. This option flags the records you want to purge 
with a X'FF' in the first data byte of a fixed-length record or the fifth byte of 
a variable-length record. QISAM ignores these flagged records during 
sequential retrieval. 

• You can get reorganization statistics by specifying the OPTCD = R DCB 
option when an ISAM data set is created. The problem program uses these 
statistics to determine the status of the the data set's overflow areas. 

• When you create an ISAM data set, you must write the records in ascending 
key order. 

For more information about coding the DCB macro to process a QISAM data 

set, see Data Administration: Macro Instruction Reference. 


Queued Sequential Access Method (QSAM) 

Before you use the QSAM access method to process a data set, consider these 

implications: 

• You can use QSAM to process all record formats except blocks with keys. 

• QSAM blocks and unblocks records for you automatically. 

• QSAM manages all aspects of I/O buffering for you automatically. The 
GET macro retrieves the next sequential logical record from the input buffer, 
and the PUT macro places the next sequential logical record in the output 

buffer. 

• QSAM gives you three transmittal modes: move, locate, and data. These 
modes give you greater flexibility managing buffers and moving data. 

For more information about coding the DCB macro to process a QSAM data 
set, see Data Administration: Macro Instruction Reference . 
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Chapter 5. Specifying a Data Control Block and Initializing Data Sets 


Before processing can begin, you must identify the characteristics of a data set, 
the volume on which it resides, and its processing requirements. During 
execution, this information is made available to the operating system in the data 
control block (DCB). A DCB is required for each data set and is created in a 
processing program by a DCB macro instruction. 

Primary sources of information to be placed in the data control block are a DCB 
macro instruction, a data definition (DD) statement, and a data set label. In 
addition, you can provide or change some of the information during execution by 
storing the pertinent data in the appropriate field of the data control block. The 
specifications needed for input/output operations are supplied during the 
initialization procedures of the OPEN macro instruction. Therefore, the 
pertinent data can be provided when your job is to be executed rather than when 
you write your program (see Figure 14 on page 42). 

When the OPEN macro instruction is executed, the OPEN routine: 

• Completes the data control block 

• Loads all necessary access method routines not already in virtual storage 

• Initializes data sets by reading or writing labels and control information 

• Builds the necessary system control blocks 

Information from a DD statement is stored in the job file control block (JFCB) 
by the operating system. When the job is to be executed, the JFCB is made 
available to the open routine. The data control block is filled in with information 
from the DCB macro instruction, the JFCB, or an existing data set label. If 
more than one source specifies information for a particular field, only one source 
is used. A DD statement takes precedence over a data set label, and a DCB 
macro instruction over both. However, you can change most data control block 
fields either before the data set is opened or when the operating system returns 
control to your program (at the data control block open exit). Some fields can 
be changed during processing. 

Figure 14 on page 42 illustrates the process and the sequence of filling in the 
data control block from various sources. The primary source is your program, 
that is, the DCB macro instruction. In general, you should use only those DCB 
parameters that are needed to ensure correct processing. The other parameters 
can be filled in when your program is to be executed. 
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When a direct access data set is opened (or a magnetic tape with standard labels 
is opened for INPUT, RDBACK, or INOUT), any field in the JFCB not 
completed by a DD statement is filled in from the data set label (if one exists). 
When opening a magnetic tape for output, the tape label is assumed not to exist 
or to apply to the current data set unless you specify DISP= MOD and a volume 
serial number in the volume parameter of the DD statement. Any field not 
completed in the DCB is filled in from the JFCB. Fields in the DCB can then 
be completed or changed by your own DCB exit routine. Then all DCB fields 
are unconditionally merged into corresponding JFCB fields if your data set is 
opened for output. This is done by specifying OUTPUT, OUTIN, EXTEND, 
or OUTINX in the OPEN macro instruction. The DSORG field is not merged 
unless this field contains zeros in the JFCB. If your data set is opened for input 
(INPUT, INOUT, RDBACK, or UPDAT is specified in the OPEN macro 
instruction), the DCB fields are not merged unless the corresponding JFCB fields 
contain zeros. 



Figure 14. Sources and Sequence of Operations for Completing the Data Control Block 


When the data set is closed, the data control block is restored to the condition it 
had before the data set was opened (the buffer pool is not freed). The open and 
close routines also use the updated JFCB to write the data set labels for output 
data sets. If the data set is not closed when your program terminates, the 
operating system will close it automatically. 

The operating system requires several types of processing information to ensure 
proper control of your input/output operations. The forms of macros in the 
program, buffering requirements, and the addresses of your special processing 
routines must be specified during either the assembly or the execution of your 
program. The DCB parameters specifying buffer requirements are discussed in 
“Managing SAM Buffer Space” on page 119. 

Because macros are expanded during the assembly of your program, you must 
supply the macro forms that are to be used in processing each data set in the 
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associated DCB macro. You can supply buffering requirements and related 
information in the DCB macro, the DD statement, or by storing the pertinent 
data in the appropriate field of the data control block before the end of your 
DCB exit routine. If the addresses of special processing routines (EODAD, 
SYNAD, or user exits) are omitted from the DCB macro, you must complete 
them in the DCB before they are required. 

Note: A data set label to JFCB merge is not performed for concatenated data 
sets at the end-of-volume time. If you want a merge, turn on the unlike attribute 
bit (DCBOFPPC) in the DCB. This attribute forces the system through OPEN 
for each data set in the concatenation, where a label to JFCB merge takes place. 


Selecting Data Set Options 

For each data set you want to process, there must be a corresponding DCB and 
DD statement. The characteristics of the data set and device-dependent 
information can be supplied by either source. Also, the DD statement must 
supply data set identification, device characteristics, space allocation requests, and 
related information as specified in JCL. You establish the logical connection 
between a DCB and a DD statement by specifying the name of the DD 
statement in the DDNAME field of the DCB macro, or by completing the field 
yourself before opening the data set. 

DCB Parameters 


After you have specified the data set characteristics in the DCB macro, you can 
change them only by changing the DCB during execution. The fields of the 
DCB discussed below are common to most data organizations and access 
techniques. (For more information about the DCB fields, see Data 
Administration: Macro Instruction Reference.) 

Block Size (BLKSIZE): Specifies the maximum length, in bytes, of a data 
block. If the records are of format F, the block size must be an integral multiple 
of the record length, except for SYSOUT data sets. (See Chapter 8, “Spooling 
and Scheduling Data Sets” on page 105.) If the records are of format V, the 
block size specified must be the maximum block size. If format-V records are 
unblocked, the block size must be 4 bytes greater than the record length 
(LRECL). When spanned variable-length records are specified, the block size is 
independent of the record length. For ISO/ANSI/FIPS Version 3 records, the 
maximum block size is 2048. 

There is no minimum requirement for block size; however, if a data check occurs 
on a magnetic tape device, any block shorter than 12 bytes in a read operation or 
18 bytes in a write operation is treated as a noise record and lost. No check for 
noise is made unless a data check occurs. The maximum block size for an 
ISO/ANSI/FIPS Version 3 tape is 2048 bytes. This limit may be overridden by a 
label validation installation exit. (See Magnetic Tape Labels and File Structure .) 
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Data Set Organization (DSORG): Specifies the organization of the data set as 
physical sequential (PS), indexed sequential (IS), partitioned (PO), or direct 
(DA). If the data set is processed using absolute rather than relative addresses, 
you must mark it as unmovable by adding a U to the DSORG parameter (for 
example, by coding DSORG = PSU). You must specify the data set organization 
in the DCB macro. When creating or processing an indexed sequential 
organization data set or creating a direct data set, you must also specify DSORG 
in the DD statement. When creating a direct data set, the DSORG in the DCB 
macro must specify PS or PSU and the DD statement must specify DA or DAU. 

Key Length (KEYLEN): Specifies the length (0 to 255) in bytes of an optional 
key that precedes each block on a direct access device. The value of KEYLEN is 
not included in BLKSIZE or LRECL but must be included in BUFL if buffer 
length is specified. Thus, BUFL= KEYLEN + BLKSIZE. 

Record Length (LRECL): Specifies the length, in bytes, of each record in the 
data set. If the records are of variable length, the maximum record length must 
be specified. For input, the field should be omitted for format-U records. For 
the extended logical record interface for ISO/ANSI/FIPS variable spanned 
records, LRECL must be specified as LRECL = OK or LRECL = nK. 

Record Format (RECFM): Specifies the characteristics of the records in the data 
set as fixed-length (F), variable-length (V), ISCII/ASCII variable-length (D), or 
undefined-length (U). Blocked records are specified as FB, VB, or DB. Spanned 
records are specified as VS, VBS, DS, or DBS. (ISCII/ASCII records are 
specified as DS or DBS.) You may also specify the records as fixed-length 
standard by using FS or FBS. You can request track overflow for records other 
than standard format by adding a T to the RECFM parameter (for example, by 
coding FBT). 

The type of print control can be specified to be in ANSI format-A or in machine 
code format-M, as described in Appendix B, “Control Characters” on page 213. 

Write Validity Check Option (OPTCD= W): You can specify the write validity 
check option in either the DCB parameter of the DD statement or the DCB 
macro. After a record is transferred from main to secondary storage, the system 
reads the stored record (without data transfer) and, by testing for a data check 
from the I/O device, verifies that the record was written correctly. Be aware that 
the write validity check process requires an additional revolution of the device for 
each record. If the system detects any errors, it starts its standard error recovery 
procedure. 

For buffered tape devices, the write validity check option delays the device end 
interrupt until the data is physically on tape. When you use the 
write-validity-check option, you get none of the performance benefits of 
buffering. 
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DD Statement Parameters 


Each of the data set description fields of the data control block, except as noted 
for data set organization, can be specified when your job is to be executed. Also, 
data set identification and disposition, and device characteristics, can be specified 
at that time. The parameters of the DD statement discussed below are common 
to most data set organizations and devices. (See JCL.) 

Device Affinity (AFF): Requests that specified data sets be allocated to the same 
device. 

Data Control Block (DCB): Provides, through sub parameters, information to 
be used to complete those fields of the data control block that were not specified 
in the DCB macro. This parameter cannot be used to change data control block 
fields that are specified in the user's program. 

Data Definition Name (DDNAME): Is the name of the DD statement and 
connects the DD statement to the data control block that specifies the same 
DDNAME. 

Data Set Disposition (DISP): Describes the status (OLD, NEW, KEEP, or 
DELETE) of a data set and shows what is to be done with it at the end of the 
job step. 

Data Set Name (DSNAME): Specifies the name of a newly defined data set, or 
refers to a previously defined data set. 

Data Set Label (LABEL): Shows the type and contents of the tape label or 
labels associated with the data set. The operating system verifies standard labels. 
Standard labels include those specified in the DD statement as SL (standard 
labels), SUL (standard user labels), AL (American National Standard labels), and 
AUL (American National Standard user labels). Nonstandard labels (NSL) can 
be specified only if your installation has incorporated into the operating system 
routines to write and process nonstandard labels. 

Space Allocation (SPACE): Designates the amount of space on a direct access 
volume that should be allocated for the data set. Unused space can be released, if 
requested, when your job is finished. 

InputjOutput Device (UNIT): Specifies the number or type of I/O devices to be 
allocated for use by the data set. 

Volume Identification (VOLUME): Identifies the particular volume or volumes, 
or the number of volumes, to be assigned to the data set, or the volumes on 
which existing data sets reside. 
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Changing the DCB 


You can complete or change the DCB during execution of your program. You 
can also determine data set characteristics from information supplied by the data 
set labels. You can make changes or additions before you open a data set, after 
you close it, during the DCB open exit routine, or while the data set is open. 
Naturally, you must supply the information before it is needed. 

Use the data control block DSECT (DCBD) macro to identify the DCB field 
names symbolically. If you load a base register with the DCB address, you can 
refer to any field symbolically. 

The DCBD macro generates a dummy control section (DSECT) named 
IHADCB. Each field name symbol consists of DCB followed by the first 5 
letters of the keyword operand for the DCB macro. For example, the symbolic 
name of the block size operand field is DCBBLKSL (For other DCB field 
names, see Data Administration: Macro Instruction Reference.) 

The attributes of each DCB field are defined in the dummy control section. Use 
the DCB macro's assembly listing to determine the length attribute and the 
alignment of each DCB field. 

You can code the DCBD macro once to describe all DCBs. 

Changing an Address in the Data Control Block: Figure 15 shows you how to 
change a field in the data control block. 



OPEN 

(TEXTDCB,INOUT) 

EOFEXIT 

CLOSE 

(TEXTDCB,REREAD),TYPE=T 


LA 

10,TEXTDCB 


USING 

IHADCB,10 


MVC 

DCB SYNAD+1(3),=AL3(OUTERROR) 


B 

OUTPUT 

INERROR 

STM 

14,12,SYNADSA+12 

OUTERROR 

STM 

14,12,SYNADSA+12 

TEXTDCB 

DCB 

DS0RG=PS,MACRF=(R,W),DDNAME=TEXTTAPE 
E0DAD=E0FEXIT,SYNAD=INERROR 


DCBD 

DS0RG=PS 


Figure 15. Changing a Field in the Data Control Block 


The data set defined by the data control block TEXTDCB is opened for both 
input and output. When the problem program no longer needs it for input, the 
EODAD routine closes the data set temporarily to reposition the volume for 
output. The EODAD routine then uses the dummy control section IHADCB to 
change the error exit address (SYNAD) from INERROR to OUTERROR. 

The EODAD routine loads the address TEXTDCB into register 10, the base 
register for IHADCB. Then it moves the address OUTERROR into the 


46 MVS/XA Data Administration Guide 



DCBSYNAD field of the DCB. Even though DCBSYNAD is a fullword field 
and contains important information in the high-order byte, change only the 3 
low-order bytes in the field. 

All unused address fields in the DCB, except DCBEXLST, are set to 1 when the 
DCB macro is expanded. Many system routines interpret a value of 1 in an 
address field as meaning no address was specified, so use it to dynamically reset 
any field you don't need. 


Opening and Closing a Data Set 

Although your program has been assembled, the various data management 
routines required for I/O operations are not a part of the object code. In other 
words, your program is not completely assembled until the DCBs are initialized 
for execution. You initialize by issuing the OPEN macro instruction to open a 
data set. After all DCBs have been completed, the system ensures that all 
required access method routines are loaded and ready for use and that all channel 
programs and buffer areas are ready. 

Access method routines are selected and loaded according to data control fields 
that indicate: 

• Data organization 

• Buffering technique 

• Access technique 

• I/O unit characteristics 

• Record format 

This information is used by the system to allocate virtual storage space and load 
the appropriate routines. These routines, the channel programs and buffer areas 
created automatically by the system, remain in virtual storage until the close 
routine signals that they are no longer needed by the DCB that was using them. 

When I/O operations for a data set are completed/you should issue a CLOSE 
macro instruction to return the DCB to its original status, handle volume 
disposition, create data set labels, complete writing of queued output buffers, and 
free virtual and auxiliary storage. 

Managing Buffer Pools When Closing Data Sets 

After closing the data set, you should issue a FREEPOOL macro instruction to 
release the virtual storage used for the buffer pool. If you plan to process other 
data sets, use FREEPOOL to regain the buffer pool storage space. If you expect 
to reopen a data set using the same DCB, use FREEPOOL unless the buffer 
pool created the first time the data set was opened will meet your needs when 
you reopen the data set. (FREEPOOL is discussed in more detail in “Buffer 
Pool Construction” on page 120.) 
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After the data set has been closed, the DCB can be used for another data set. If 
you do not close the data set before a task terminates, the operating system closes 
it automatically. If the DCB is not available to the system at that time, the 
operating system abnormally ends the task, and data results can be unpredictable. 
Note, however, that the operating system cannot automatically close any open 
data sets after the normal end of a program that was brought into virtual storage 
by the loader. Therefore, loaded programs must include CLOSE macro 
instructions for all open data sets. 

Simultaneous Opening and Closing of Multiple Data Sets 

An OPEN or CLOSE macro instruction can be used to begin or end processing 
of more than one data set. Simultaneous opening or closing is faster than issuing 
separate macro instructions; however, additional storage space is required for each 
data set specified. The coding examples in Figure 16 on page 52 and Figure 18 
on page 54 show the macro expansions for simultaneous open and close 
operations. 

Opening and Closing Data Sets Shared by More Than One Task 

When more than one task is sharing a data set, the following restrictions must be 
recognized. Failure to adhere to these restrictions endangers the integrity of the 
shared data set. 


• All tasks sharing a DCB must be in the job step that opened the DCB (see 
“Sharing Data Sets” on page 69). 

• Each task sharing a DCB must ensure that all the input and output 
operations it starts using a given DCB are complete, before the task 
terminates. A CLOSE macro instruction issued for the DCB will ensure 
termination of all input and output operations. 

• A DCB can be closed only by the task that opened it. 


| Considerations for Allocating Direct Access Data Sets 

| When you allocate space for a new data set on a direct access volume, the tracks 

| contain unknown data. A program that tries to access data on these tracks before 

| known data is written on them may get unpredictable results, such as program 

| checks or I/O errors. The program may even appear to run correctly! 


If you must access a newly allocated data set before you put known data into it, 
use one of the following methods to make it appear empty: 

1. At allocation time, specify a primary allocation value of zero; such as 
SPACE = (TRK,(0,10)) or SPACE = (CYL,(0,50)). This method prevents 
processing certain labels if user labels are requested (LABEL =(,SUL)). 

2. After allocation time, run a program that opens the data set for output and 
closes it without writing anything. This puts an end-of-file mark at the 
beginning of the data set. 
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Considerations for Opening and Closing Data Sets 

• Two or more DCBs should never be concurrently open for output to the 
same data set, except with the basic indexed sequential access method 
(BISAM). 

• If, concurrently, one DCB is open for input or update, and one for output to 
the same data set on a direct access device, the input or update DCB may be 
unable to read what the output DCB wrote if the output DCB extended fhe 
data set. 

• If you want to use the same DD statement for two or more DCBs, you 
cannot specify parameters for fields in the first DCB and then be assured of 
obtaining the default parameters for the same fields in any other DCB using 
the same DD statement. This is true for both input and output and is 
especially important when you are using more than one access method. Any 
action on one DCB that alters the JFCB affects the other DCBs and thus 
can cause unpredictable results. Therefore, unless the parameters of all DCBs 
using one DD statement are the same, you should use separate DD 
statements. 

• Associated data sets for the IBM 3525 Card Punch can be opened in any 
order, but all data sets must be opened before any processing can begin. 
Associated data sets can be closed in any order, but, after a data set has been 
closed, I/O operations cannot be performed on any of the associated data 
sets. See Programming Support for the IBM 3505 Card Reader and the IBM 
3525 Card Punch for more information. 

• The OPEN macro gets user control blocks and user storage in the protection 
key that is specified in the TCB(TCBPKF). Therefore, any task that 
processes the DCB (such as Open, Close, or EOV) must be in the same 
protection key specified in the TCB, or must be in key 0. Also, the Open 
and Close must be done in the same key. 

Note: If the Open is done while processing in key 0, then user storage 
obtained by Open will be from subpool 252. 

• Volume disposition specified in the OPEN or CLOSE macro instruction can 
be overridden by the system if necessary. However, you need not be 
concerned; the system automatically requests the mounting and demounting 
of volumes, depending on the availability of devices at a particular time. 
Additional information on volume disposition is provided in JCL. 

Open/Close/EOV Errors 

There are two classes of errors that can occur during open, close, and 
end-of-volume processing: determinate and indeterminate errors. Determinate 
errors are errors associated with a system completion code. For example, a 
condition associated with the 213 completion code with a return code of 04 might 
be detected during open processing, indicating that a format-1 DSCB could not 
be found for a data set being opened. Indeterminate errors are errors that cannot 
be anticipated, such as program checks. 
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Installation exits 


If a determinate error occurs during the processing resulting from a concurrent 
OPEN or CLOSE macro instruction, an attempt will be made to complete open 
or close processing of the DCBs that are riot associated with the DCB in error. 
Note that you can also choose to abnormally end the task immediately by coding 
a DCB abend exit routine that shows the “immediate termination” option (see 
“DCB Abend Exit” on page 97). When all open or close processing is 
completed, abnormal end processing is begun. Abnormal end involves forcing all 
DCBs associated with a given OPEN or CLOSE macro to close status, thereby 
freeing all storage devices and other system resources related to the DCBs. 

If an indeterminate error (such as a program check) occurs during open, close, or 
EOV processing, no attempt is made by the system control program to complete 
concurrent open or close processing. The DCBs associated with the OPEN or 
CLOSE macro are forced to close status if possible, and the resources related to 
each DCB are freed. 


To determine the status of any DCB after an error, the OPEN (CLOSE) return 
code in register 15 must be interrogated for the following values: 


Return Code Meaning 


00 (XW) 
04 (XW) 

08 (XW) 

12 (X'OC 7 ) 


All entries in the parameter list opened successfully. 

All entries in the parameter list have successfully 
completed open, but one or more entries have a warning 
message. 

One or more entries in the parameter list were not 
opened successfully. The entries with errors are restored 
to their preopen status. 

One or more entries in the parameter list were not 
opened successfully. 


The entries with errors are not restored, and cannot be reopened without 
restoration. 


During task termination, the system issues a CLOSE macro for each data set that 
is still open. If this is an abnormal termination for QSAM, the close routines 
that would normally finish processing buffers are bypassed. Any outstanding I/O 
requests are purged. Thus, your last data records may be lost for a QSAM 
output data set. 

It is a good procedure to close an ISAM data set before task termination because, 
if an I/O error is detected, the ISAM close routines cannot return the problem 
program registers to the SYNAD routine, causing unpredictable results. 



v. 


Four installation exit routines are provided for abnormal end with 
ISO/ANSI/FIPS Version 3 tapes. 

• The label validation exit is entered during open/EOV if an invalid label 
condition is detected, and label validation has not been suppressed. Invalid 
conditions include incorrect alphameric fields, nonstandard values (for 
example, RECFM = U, block size greater than 2048, or a zero generation 
number), invalid label sequence, nonsymmetrical labels, invalid expiration 
date sequence, and duplicate data set names. 
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• The validation suppression exit is entered during open/EOV if volume 
security checking has been suppressed, if the volume label accessibility field 
contains an ISCII/ASCII space character, or if RACF accepts a volume and 
the accessibility field does not contain an uppercase A through Z. 

• The volume access exit is entered during open/EOV if a volume is not 
RACF protected and the accessibility field in the volume label contains an 
ISCII/ASCII uppercase A through Z. 

• The file access exit is entered after positioning to a requested data set if the 
accessibility field in the HDR1 label contains an ISCII/ASCII uppercase A 
through Z. 

For additional information about ISO/ANSI/FIPS Version 3 installation exits, 
see Magnetic Tape Labels and File Structure . 

OPEN—Prepare a Data Set for Processing 

The OPEN macro instruction is used to complete a data control block for an 
associated data set. The OPEN macro parameters identify the method of 
processing and volume positioning in the event of an end-of-volume condition. 


Processing Method 


You can process a data set as either input or output. This is done by coding 
INPUT, OUTPUT, or EXTEND as the processing method operand of the 
OPEN macro. For BSAM, code INOUT, OUTIN, or OUTINX. If the data set 
resides on a direct access volume, you can code UPDAT in the processing 
method operand to show that records can be updated. By coding RDBACK in 
this operand, you can specify that a magnetic tape volume containing format-F 
or format-U records is to be read backward. (Variable-length records cannot be 
read backward.) If the processing method operand is omitted from the OPEN 
macro instruction, INPUT is assumed. The operand is ignored by the basic 
indexed sequential access method (BISAM); it must be specified as OUTPUT or 
EXTEND when you are using the queued indexed sequential access method 
(QISAM) to create an indexed sequential data set. You can override the INOUT, 
OUTIN, UPDAT, or OUTINX at execution time by using the LABEL 
parameter of the DD statement, as discussed in JCL. 

Note: Unless label validation has been suppressed, OPEN for MOD (OLD 
OUTPUT/OUTIN), INOUT, EXTEND, or OUTINX cannot be processed for 
ISO/ANSI/FIPS Version 3 tapes, because this kind of processing updates only 
the closing label of the file, causing a label symmetry conflict. An unmatching 
label should not frame the other end of the file. 

SYSIN and SYSOUT data sets must be opened for INPUT and OUTPUT, 
respectively. INOUT is treated as INPUT; OUTIN, EXTEND, or OUTINX is 
treated as OUTPUT. UPDAT and RDBACK cannot be used. 

In Figure 16 on page 52, the data sets associated with three DCBs are to be 
opened simultaneously. 
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OPEN 

(TEXTDCB,,CONVDCB, (OUTPUT),PRINTDCB, 
(OUTPUT)) 

+ 

CNOP 

0,4 

Align list to fullword 

+ 

BAL 

1,*+16 

AL1(0) 

Load regl w/list address 

+ 

DC 

Option byte 

+ 

DC 

AL3(TEXTDCB) 

DCB address 

+ 

DC 

AL1(15) 

Option byte 

+ 

DC 

AL3(CONVDCB) 

DCB address 

+ 

DC 

AL1(143) 

Option byte 

+ 

DC 

AL3(PRINTDCB) 

DCB address 

+ 

SVC 

19 

Issue open SVC 


Figure 16. Opening Three Data Sets Simultaneously 


Because no processing method operand is specified for TEXTDCB, the system 
assumes INPUT. Both CONVDCB and PRINTDCB are opened for output. 
No volume positioning options are specified; thus, the disposition indicated by 
the DD statement DISP parameter is used. 

At execution, the SVC 19 instruction passes control to the open routine, which 
initializes the three DCBs and loads the appropriate access method routines. 


CLOSE—Temiinate Processing of a Data Set 

The CLOSE macro instruction is used to terminate processing of a data set and 
release it from a DCB. The volume positioning (tapes only) that is to result from 
closing the data set can also be specified. Volume positioning options are the 
same as those that can be specified for end-of-volume conditions in the OPEN 
macro instruction or the DD statement. An additional volume positioning 
option, REWIND, is available and can be specified by the CLOSE macro 
instruction for magnetic tape volumes. REWIND positions the tape at the load 
point regardless of the direction of processing. 

You can code CLOSE TYPE = T and perform some close functions for 
sequential data sets on magnetic tape and direct access volumes processed with 
BSAM. When you use TYPE = T, the DCB used to process the data set 
maintains its open status. You don't have to issue another OPEN macro 
instruction to continue processing the same data set. This option cannot be used 
in a SYNAD routine. 

The TYPE = T operand causes the system control program to process labels, 
modify some of the fields in the system control blocks for that data set, and 
reposition the volume (or current volume in the case of multivolume data sets) in 
much the same way that the normal CLOSE macro does. When you code 
TYPE = T, you can specify that the volume is either to be positioned at the end 
of data (the LEAVE option) or to be repositioned at the beginning of data (the 
REREAD option). Magnetic tape volumes are repositioned either immediately 
before the first data record or immediately after the last data record; the presence 
of tape labels has no effect on repositioning. Figure 17 on page 53, which 
assumes a sample data set containing 1000 records, illustrates the relationship 
between each positioning option and the point where you resume processing the 
data set after issuing the temporary close. 
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Begin processing 
tape data set 
(open for read 
backward) \ 


Record 

Record 

Record 

-* 1 - 

Record 

Record 

1 

2 

3 


999 

1000 




-J t - 




If you CLOSE TYPE = T and specify 

After temporary close, you will 
resume processing 

LEAVE 

Immediately after record 1000 

LEAVE (with tape data set open 
for read backward) 

Immediately before record 1 

REREAD 

Immediately before record 1 

REREAD (with tape data set open 
for read backward) 

Immediately after record 1000 


Figure 17. Record Processed When LEAVE or REREAD Is Specified for CLOSE 
TYPE = T 


If you code the release (RLSE) operand on the DD statement for an output data 
set, it is ignored by temporary close (CLOSE TYPE = T). However, if the last 
operation was a write, then normal close (without TYPE = T) releases any 
unused space. 

Space is released on a track boundary if the extent containing the last record was 
allocated in units of tracks or in units of average block lengths with ROUND not 
specified. Space is released on a cylinder boundary if the extent containing the last 
record was allocated in units of cylinders or in units of average block lengths with 
ROUND specified. However, a cylinder boundary extent may be released on a 
track boundary if: 

• The DD statement used to access the data set contains a space parameter 
specifying units of tracks or units of average block lengths with ROUND not 
specified, or 

• No space parameter is supplied in the DD statement and no secondary space 
value has been saved in the format-1 DSCB for the data set. (This may occur 
if the release indicator is set in the JFCB through RDJFCB and OPEN 
TYPE = J, or through the OPEN installation exit.) In this case, the 
performance benefit of cylinder boundaries is lost. 

For data sets processed with BSAM, you can use CLOSE TYPE = T with the 
following restrictions: 

• The DCB for the data set you are processing on a direct access device must 
specify either DSORG= PS or DSORG= PSU for input processing, and 
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either DSORG= PS, DSORG= PSU, DSORG = PO, or DSORG= POU for 
output processing. 




• The DCB must not be open for input to a member of a partitioned data set. 

• If you open a data set on a direct access device for output and issue CLOSE 
TYPE = T, the volume will be repositioned only if the data set was created 
with DSORG= PS, DSORG = PSU, DSORG = PO, or DSORG=POU 
(you cannot specify the REREAD option if DSORG= PO or 

DSORG= POU is specified). (This restriction prohibits the use of temporary 
close following or during the building of a BDAM data set that is created by 
specifying BSAM MACRF = WL.) 

• If you open the data set for input and issue CLOSE TYPE = T with the 
LEAVE option, the volume will be repositioned only if the data set specifies 
DSORG= PS or DSORG = PO. 

Note: When a data control block is shared among multiple tasks, only the task 
that opened the data set can close it unless TYPE = T is specified. 

Before issuing the CLOSE macro, a CHECK macro must be issued for all 
DECBs that have outstanding I/O from WRITE macro instructions. When 
CLOSE TYPE = T is specified, a CHECK macro must be issued for all DECBs 
that have outstanding I/O from either WRITE or READ macro instructions. 

In Figure 18, the data sets associated with three DCBs are to be closed 
simultaneously. 



. CLOSE 

(TEXTDCB,,C0NVDCB, 

,PRINTDCB) 

+ 

CNOP 

0,4 

Align list to fullword 

+ 

BAL 

1,*+16 

Load regl w/list addr 

+ 

DC 

AL1(0) 

Option byte 

+ 

DC 

AL3(TEXTDCB) 

DCB address 

+ 

DC 

AL1(0) 

Option byte 

+ 

DC 

AL3(C0NVDCB) 

DCB address 

+ 

DC 

AL1(128) 

Option byte 

+ 

DC 

AL3(PRINTDCB) 

DCB address 

+ 

SVC 

20 

Issue close SVC 


Figure 18. Closing Three Data Sets Simultaneously 


Because no volume positioning operands are specified, the position indicated by 
the DD statement DISP parameter is used. 


Volume Positioning 

At execution, the SVC 20 instruction passes control to the close routine, which 
ends the processing of the three data sets and returns the three DCBs to their 
original status. 
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Releasing Data Sets and Volumes 

You are offered the option of being able to release data sets and the volumes the 
data sets reside on when your task is no longer using them. If you are not 
sharing data sets, these data sets would otherwise remain unavailable for use by 
other tasks until the job step that opened them is terminated. 

There are two ways to code the CLOSE macro instruction that can result in 
releasing a data set and the volume on which it resides at the time the data set is 
closed: 

In conjunction with the FREE = CLOSE parameter of the DD statement, you 
can code: 

CLOSE (DCB1,DISP) or 
CLOSE (DCB1,REWIND) 

If you do not code FREE = CLOSE on the DD statement, you can code: 

CLOSE (DCB1,FREE) 

See JCL for information about how to use and code the FREE = CLOSE 
parameter of the DD statement. 

In either case, tape data sets and volumes are freed for use by another job step. 
Data sets on direct access devices will be freed and the volumes on which they 
reside will be freed if no other data sets on the volume are open. Additional 
information on volume disposition is provided in JCL . 

Data sets being temporarily closed (using CLOSE TYPE = T) cannot be released 
at the time the data set is closed. They will be released at the end of the job step. 

For additional information and coding restrictions on the CLOSE macro, see 
Data Administration: Macro Instruction Reference. 

End-of-Volume Processing 

The access methods pass control to the data management end-of-volume routine 
when any of the following conditions is detected: 

• Tapemark (input tape volume). 

• Filemark or end of last extent (input direct access volume). 

• End-of-data indicator (input device other than magnetic tape or direct access 
volume). An example of this would be the last card read on a card reader. 

• End of reel (output tape volume). 

• End of extent (output direct access volume). 

You may issue a force end-of-volume (FEOV) macro instruction before the 
end-of-volume condition is detected. 
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If the LABEL parameter of the associated DD statement shows standard labels, 
the end-of-volume routine checks or creates standard trailer labels. If SUL or 
AUL is specified, control is passed to the appropriate user label routine if it is 
specified in your exit list. 

If multiple volume data sets are specified in your DD statement, automatic 
volume switching is accomplished by the end-of-volume routine. When an 
end-of-volume condition exists on an output data set, additional space is 
allocated as indicated in your DD statement. If no more volumes are specified or 
if more than specified are required, the storage is obtained from any available 
volume on a device of the same type. If no such volume is available, your job is 
terminated. 

Volume Positioning for Tapes 

When an end-of-volume condition is detected, the system positions the volume 
according to the disposition specified in the DD statement unless the volume 
disposition is specified in the OPEN macro instruction. Volume positioning 
instructions for a sequential data set on magnetic tape can be specified as LEAVE 
or REREAD. 

LEAVE 

positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled volume to the point following 
the tapemark that follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 

If the tape was last read backward: 

LEAVE 

positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 

REREAD 

positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled tape to the point following the 
tapemark that follows the last block of the data set. 

If, however, you want to position the current volume according to the option 
specified in the DISP parameter of the DD statement, you code DISP in the 
OPEN macro instruction. 

DISP 

specifies that a tape volume is to be disposed of in the manner implied by 
the DD statement associated with the data set. Direct access volume 
positioning and disposition are not affected by this parameter of the OPEN 
macro instruction. There are several dispositions that can be specified in 
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the DISP parameter of the DD statement; DISP can be PASS, DELETE, 
KEEP, CATLG, or UNCATLG. 


The resultant action at the time an end-of-volume condition arises depends 
on (1) how many tape units are allocated to the data set and (2) how many 
volumes are specified for the data set in the DD statement. This is 
determined by the UNIT and VOLUME parameters of the DD statement 
associated with the data set. If the number of volumes is greater than the 
number of units allocated, the current volume will be rewound and 
unloaded. If the number of volumes is less than or equal to the number of 
units, the current volume is merely rewound. 

For magnetic tape volumes that are not being unloaded, positioning varies 
according to the direction of the last input operation and the existence of 
tape labels. 

If the tape was last read forward: 

LEAVE 

positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled volume to the point following 
the tapemark that follows the last block of the data set. 

REREAD 

positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 

If the tape was last read backward: 

LEAVE 

positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 

REREAD 

positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled tape to the point following the 
tapemark that follows the last block of the data set. 


FEOV-Force End of Volume 

The FEOV macro instruction directs the operating system to start the 
end-of-volume processing before the physical end of the current volume is 
reached. If another volume has been specified for the data set, volume switching 
takes place automatically. The volume positioning options REWIND and 
LEAVE are available. 

If an FEOV macro is issued for a spanned multivolume data set that is being read 
using QSAM, errors may occur when the next GET macro is issued. These 
errors are documented in “Spanned Format-VS Records (Sequential Access 
Method)” on page 19. 
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The FEOV macro instruction can only be used when you are using BSAM or 
QSAM. FEOV is ignored if issued for a SYSIN or SYSOUT data set. 


Device Independence 

The ability to request input/output operations without regard for the physical 
characteristics of the I/O devices makes it possible for you to write one program 
that will fulfill a variety of needs. Device independence may be useful for: 

• Accepting data from a number of recording devices, such as a disk pack, 7- or 
9-track magnetic tape, or unit-record equipment. This situation could arise 
when several types of data-acquisition devices are feeding a centralized 
complex. 

• Observing constraints imposed by the availability of input/output devices (for 
example, when devices on order have not been installed). 

• Assembling, testing, and debugging on one system configuration and 
processing on a different configuration. For example, an IBM 3330 Disk 
Storage drive can be used as a substitute for several magnetic tape units. 

Device independence is not difficult to achieve, but requires some programming 
considerations. See below. 

Programming Considerations 

Each of three data set organizations—partitioned, indexed sequential, and 
direct—requires the use of a direct access device. Device independence is 
meaningful, then, only for a sequentially organized data set, that is, a data set in 
which one block of data follows another, thus allowing input or output to be on 
a magnetic tape drive, a direct access device, a card read/punch, a printer, or a 
spooled data set. 

Your program will be device independent if you do two things: 

• Omit all device-dependent macros and macro instruction parameters from 
your program. 

• Defer specifying any required device-dependent parameters until the program 
is ready for execution. That is, supply the parameters on your data definition 
(DD) statement or during the open exit routine. 

In examining the following list of macros, consider only the logical layout of your 
data record without regard for the type of device used. Also, consider that any 
reference to a direct access volume is to be treated as a reference to magnetic 
tape, that is, you must create a new data set rather than attempt to update. 

OPEN 

Specify INPUT, OUTPUT, INOUT, OUTIN, OUTINX, or EXTEND. 
The parameters RDBACK and UPDAT are device dependent and cause an 
abnormal termination if directed to a device of the wrong type. 
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READ 

Specify forward reading (SF) only. 

WRITE 

Specify forward writing (SF) only; use only to create new records or modify 
existing records. 

PUTX 

Use only output mode. 

NOTE/POINT 

These macros are valid for both magnetic tape and direct access volumes. 


BSP 

This macro is valid for magnetic tape or direct access volumes. However, 
its use would be an attempt to perform device-dependent action. 

CNTRL/PRTOV 

These macros are device dependent. 

DCB Subparameters 

MACRF 

Specify R/W or G/P. Processing mode can also be indicated. 

DEVD 

Specify DA if any direct access device may be used. Magnetic tape and 
unit-record equipment DCBs will fit in the area provided during assembly. 
Specify unit-record devices only if you expect never to change to tape or 
direct access devices. 

KEYLEN 

Can be specified on the DD statement if necessary. 

RECFM, LRECL, BLKSIZE 

These can be specified in the DD statement. However, you must consider 
maximum record size for specific devices, and track overflow cannot be 
specified unless supported. Also, you must consider whether you expect to 
process XLRI records. 

DSORG 

Specify sequential organization (PS or PSU) to get the full DCB 
expansion. 

OPTCD 

This subparameter is device dependent; specify it in the DD statement. 
SYNAD 

Any device-dependent error checking is automatic. Generalize your routine 
so that no device-dependent information is required. 
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Chapter 6. Accessing Records in Data Sets 


Accessing Data with READ/WRITE 


The basic access technique provides the READ and WRITE macro instructions 
for transmitting data between virtual and auxiliary storage. This technique is 
used when you want to process records other than sequentially or when you do 
not want some or all of the automatic functions performed by the queued access 
technique. Although the system does not provide anticipatory buffering or 
synchronized scheduling, macro instructions are provided to help you program 
these operations. 

The READ and WRITE macro instructions process blocks, not records. Thus, 
blocking and unblocking of records are your responsibility. Buffers, allocated by 
either you or the operating system, are filled or emptied individually each time a 
READ or WRITE macro instruction is issued. Moreover, the READ and 
WRITE macro instructions only start input/output operations. To ensure that 
the operation is completed successfully, you must issue a CHECK macro 
instruction to test the data event control block (DECB). (The only exception to 
this is that, when the SYNAD or EODAD routine is entered, a CHECK macro 
instruction should not be issued for outstanding READ or WRITE requests.) 
The number of READ or WRITE macro instructions issued before a CHECK 
macro instruction is used should not exceed the specified number of channel 
programs (NCP). 

Grouping Related Control Blocks in a Paging Environment 

Related control blocks (the DCB and DECB) and data areas (buffers and key 
areas) should be coded so they assemble in the same area of your program. This 
will reduce the number of paging operations required to read from and write to 
your data set. 

Note: DCB, DECB, and buffers must reside below 16 megabytes. 

Using Overlapped I/O with BSAM 

When using BSAM with overlapped I/O (multiple I/O requests outstanding at 
one time), more than one DECB must be used. A different DECB should be 
specified for each channel program. For example, if you specify NCP = 3 in your 
DCB for the data set and you are reading records from the data set, you should 
code the following macros in your program: 
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READ DECB1,. 
READ DECB2,. 
READ DECB3,. 
CHECK DECB1 
CHECK DECB2 
CHECK DECB3 


READ—Read a Block 


The READ macro retrieves a data block from an input data set and places it in a 
designated area of virtual storage. To aHow overlap of the input operation with 
processing, the system returns control to your program before the read operation 
is completed. The DECB created for the read operation must be tested for 
successful completion before the record is processed or the DECB is reused. 

If an indexed sequential data set is being read, the block is brought into virtual 
storage and the address of the record is returned to you in the DECB. 

When you use the READ macro for BSAM to read a direct data set with 
spanned records and keys and you specify BFTEK = R in your DCB, the data 
management routines displace record segments after the first in a record by key 
length. Thus, you can expect the block descriptor word and the segment 
descriptor word at the same locations in your buffer or buffers, regardless of 
whether you read the first segment of a record, preceded in the buffer by its key, 
or a subsequent segment that does not have a key. This procedure is caHed offset 
reading. 

You can specify variations of the READ macro according to the organization of 
the data set being processed and the type of processing to be done by the system 
as foHows: 

Sequential 

SF Read the data set sequentiaUy. 

SB Read the data set backward (magnetic tape, format-F and format-U only). 
When RECFM= FBS, data sets with the last block truncated cannot be 
read backward. 

Indexed Sequential 

K Read the data set. 

KU Read for update. The system maintains the device address of the record; 
thus, when a WRITE macro returns the record, no index search is required. 

Direct 

D Use the direct access method. 

I Locate the block using a block identification. 
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K Locate the block using a key. 

F Provide device position feedback. 

X Maintain exclusive control of the block. 

R Provide next address feedback. 

U Next address can be a capacity record or logical record, whichever occurred 
first. 

WRITE-Write a Block 

The WRITE macro places a data block in an output data set from a designated 
area of virtual storage. The WRITE macro can also be used to return an 
updated record to a data set. To allow overlap of output operations with 
processing, the system returns control to your program before the write operation 
is completed. The DECB created for the write operation must be tested for 
successful completion before the DECB can be reused. For ISCII/ASCII tape 
data sets, do not issue more than one WRITE on the same record, because the 
WRITE macro instruction causes the data in the record area to be translated 
from EBCDIC to ISCII/ASCII. 

As with the READ macro, you can specify variations of the WRITE macro 
according to the organization of the data set and the type of processing to be 
done by the system as follows: 

Sequential 

SF Write the data set sequentially. 

Indexed Sequential 

K Write a block containing an updated record, or replace a record with a 
fixed, unblocked record having the same key. The record to be replaced 
need not have been read into virtual storage. 

KN Write a new record or change the length of a variable-length record. 

Direct 

SD Write a dummy fixed-length record. (BDAM load mode) 

SZ Write a capacity record (RO). The system supplies the data, writes the 
capacity record, and advances to the next track. (BDAM load mode) 

SFR Write the data set sequentially with next-address feedback. (BDAM load 
mode variable spanned) 

D Use the direct access method. 

I Search argument identifies a block. 
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K Search argument is a key. 

A Add a new block. 

F Provide record location data (feedback). 

X Release exclusive control. 

CHECK—Test Completion of Read or Write Operation 

When processing a data set, you can test for completion of a READ or WRITE 
request by issuing a CHECK macro. The system tests for errors and exceptional 
conditions in the data event control block (DECB). Successive CHECK macros 
issued for the same data set must be issued in the same order as the associated 
READ and WRITE macros. 

The check routine passes control to the appropriate exit routines specified in the 
DCB for error analysis (SYNAD) or, for sequential data sets, end-of-data 
(EODAD). It also automatically starts the end-of-volume procedures (volume 
switching or extending output data sets). 

If you specify OPTCD = Q in the DCB, CHECK causes input data to be 
translated from ISCII/ASCII to EBCDIC. 

WAIT—Wait for Completion of a Read or Write Operation 

When processing a data set, you can test for completion of any READ or 
WRITE request by issuing a WAIT macro. The input/output operation is 
synchronized with processing, but the DECB is not checked for errors or 
exceptional conditions, nor are end-of-volume procedures initiated. Your 
program must perform these operations. 

For BDAM and BISAM, a WAIT macro must be issued for each READ or 
WRITE macro if MACRF = C is not coded in the associated DCB. When 
MACRF = C is coded, and always for BSAM and BPAM, a CHECK macro 
must be issued for each READ or WRITE macro. Because the CHECK macro 
incorporates the function of the WAIT macro, a WAIT is normally redundant 
for those access methods. The ECBLIST form of the WAIT macro may be 
useful, though, in selecting which of several outstanding events should be checked 
first. 

The WAIT macro can be used to await completion of multiple read and write 
operations. Each operation must then be checked or tested separately. Example: 
You have opened an input DCB for BSAM with NCP = 2, and an output DCB 
for BISAM with NCP= 1 and without specifying MACRF = C. You have issued 
two BSAM READ macros and one BISAM WRITE macro. You now issue the 
WAIT macro with ECBLIST pointing to the BISAM DECB and the first 
BSAM DECB. (Because BSAM requests are serialized, the first request must 
execute before the second.) When you regain control, you will inspect the 
DECBs to see which has completed (second bit on). If it was BISAM, you will 
issue another WRITE macro. If it was BSAM, you will issue a CHECK macro 
and then another READ macro. 
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Data Event Control Block (DECB) 


A data event control block is a 16- to 32-byte area reserved by each READ or 
WRITE macro. It contains the ECB, control information, and pointers to 
control blocks. The DCB is described in Appendix A of Data Administration: 
Macro Instruction Reference . 

The DECB is examined by the check routine when the I/O operation is 
completed to determine if an uncorrectable error or exceptional condition exists. 
If it does, control is passed to your SYNAD routine. If you have no SYNAD 
routine, the task is abnormally terminated. 


Accessing Data with GET/PUT 

The queued access technique provides GET and PUT macros for transmitting 
data within virtual storage. These macro instructions cause automatic blocking 
and unblocking of the records stored and retrieved. Anticipatory (look-ahead) 
buffering and synchronization (overlap) of input and output operations with 
instruction stream processing are automatic features of the queued access method. 

Because the operating system controls buffer processing, you can use as many 
input/output (I/O) buffers as needed without reissuing GET or PUT macro 
instructions to fill or empty buffers. Usually, more than one input block is in 
storage at a time, so I/O operations do not delay record processing. 

Because the operating system synchronizes input/output with processing, you 
need not test for completion, errors, or exceptional conditions. After a GET or 
PUT macro is issued, control is not returned to your program until an input area 
is filled or an output area is available. Exits to error analysis (SYNAD) and 
end-of-volume or end-of-data (EODAD) routines are automatically taken when 
necessary. 

GET—Retrieve a Record 

The GET macro is used to obtain a record from an input data set. It operates in 
a logical sequential and device-independent manner. As required, the GET 
macro schedules the filling of input buffers, unblocks records, and directs input 
error recovery procedures. For sequential data sets, it also merges record 
segments into logical records. After all records have been processed and the GET 
macro detects an end-of-data indication, the system automatically checks labels 
on sequential data sets and passes control to your end-of-data (EODAD) routine. 
If an end-of-volume condition is detected for a sequential data set, the system 
provides automatic volume switching if the data set extends across several 
volumes or if concatenated data sets are being processed. If you specify 
OPTCD - Q in the DCB, GET causes input data to be translated from 
ISCII/ASCII to EBCDIC. 
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PUT-Write a Record 


The PUT macro is used to write a record into an output data set. Like the GET 
macro, it operates in a logical sequential and device-independent manner. As 
required, the PUT macro blocks records, schedules the emptying of output 
buffers, and handles output error correction procedures. For sequential data sets, 
it also starts automatic volume switching and label creation, and also segments 
records for spanning. If you specify OPTCD = Q in the DCB, PUT causes 
output to be translated from EBCDIC to ISCII/ASCII. 

If the PUT macro is directed to a card punch or printer, the system automatically 
adjusts the number of records or record segments per block of format-F or 
format-V blocks to 1. Thus, you can specify a record length (LRECL) and block 
size (BLKSIZE) to provide an optimum block size if the records are temporarily 
placed on magnetic tape or a direct access volume. 

For spanned variable-length records, the block size must be equivalent to the 
length of one card or one print line. Record size may be greater than block size 
in this case. 


PUTX--Write an Updated Record 

The PUTX macro is used to update a data set or to create an output data set 
using records from an input data set as a base. PUTX updates, replaces, or 
inserts records from existing data sets but does not create records. 

When you use the PUTX macro to update, each record is returned to the data 
set referred to by a previous locate mode GET macro instruction. The buffer 
containing the updated record is flagged and written back to the same location on 
the direct access storage device where it was read. The block is not written until 
a GET macro instruction is issued for the next buffer, except when a spanned 
record is to be updated. In that case, the block is written with the next GET 
macro. 

When the PUTX macro is used to create an output data set, you can add new 
records by using the PUT macro. As required, the PUTX macro blocks records, 
schedules the writing of output buffers, and handles output error correction 
procedures. 

Parallel Input Processing (QSAM Only) 

QSAM parallel input processing may be used to process two or more input data 
sets concurrently, such as sorting or merging several data sets at the same time. 
This eliminates the need for issuing a separate GET macro to each DCB 
processed. The get routine for parallel input processing selects a DCB with a 
ready record and then transfers control to the normal get routine. If there is no 
DCB with a ready record, a multiple WAIT macro is issued. 

Parallel input processing provides a logical input record from a queue of data sets 
with equal priority. The function supports QSAM with input processing, simple 
buffering, locate or move mode, and fixed-, variable-, or undefined-length records. 
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Spanned records, track-overflow records, dummy data sets, and SYSIN data sets 
are not supported. 

Parallel input processing can be interrupted at any time to retrieve records from a 
specific data set, or to issue control instructions to a specific data set. When the 
retrieval process has been completed, parallel input processing may be resumed. 

Data sets can be added to or deleted from the data set queue at any time. It is 
important to note, however, that, as each data set reaches an end-of-data 
condition, the data set must be removed from the queue with the CLOSE macro 
before a subsequent GET macro is issued for the queue; otherwise, the task may 
be ended abnormally. 

A request for parallel input processing is indicated by including the address of a 
parallel data access block (PDAB) in the DCB exit list. For additional 
information on the DCB exit list, see Chapter 7, “DCB Exit Routines’’ on 
page 75. 

With the use of the PDAB macro, you can create and format a work area that 
identifies the maximum number of DCBs that can be processed at any one time. 
If you exceed the maximum number of entries indicated in the PDAB macro 
when adding a DCB to the queue with the OPEN macro, the data set will not be 
available for parallel input processing; however, it may be available for sequential 
processing. 

When issuing a parallel GET macro, register 1 must always point to a PDAB. 
You may load the register or let the GET macro do it for you. When control is 
returned to you, register 1 contains the address of a logical record from one of the 
data sets in the queue; registers 2 through 13 contain their original contents at the 
time the GET macro was issued; registers 14, 15, and 0 are changed. 

Through the PDAB, you can find the data set from which the record was 
retrieved. A fullword address in the PDAB (PDADCBEP) points to the address 
of the DCB. It should be noted that this pointer may be invalid from the time a 
CLOSE macro is issued to the issuing of the next parallel GET macro. 

In Figure 19 on page 68, not more than three data sets (MAXDCB = 3 in the 
PDAB operand) will be open for parallel processing at a time. If data definition 
statements and data sets are supplied, DATASET 1, DATASET2, and 
DATASET3 will be opened for parallel input processing as specified in the input 
processing OPEN macro. Other attributes of each data set are QSAM 
(MACRF = G), simple buffering by default, locate or move mode (MACRF = L 
or M), fixed-length records (RECFM= F), and exit fist entry for a PDAB 
(X'92'). Note that both locate and move modes may be used in the same data 
set queue. The mapping macros, DCBD and PDABD, are used to reference the 
DCBs and the PDAB respectively. 
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BZ 
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L 
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BL 
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DATASET2 

DCB 

DATASET3 

DCB 

DATASET4 

DCB 

DCBQUEUE 

SET3XLST 

ZEROS 

PDAB 

DC 

DC 

DCBD 

PDABD 


(DATASET1,(INPUT),DATASET2,(INPUT),DATASET3, 

(INPUT), DATASET4, ( OUTPUT) ) 

DATASET1+DCBQSWS-IHADCB,DCBPOPEN Opened for 

parallel processing 

SEQRTN Branch on no to 

sequential routine 
DATASET2+DCBQSWS-IHADCB,DCBPOPEN 
SEQRTN 

DATASET3+DCBQSWS-IHADCB,DCBPOPEN 
SEQRTN 

DCBQUEUE,BUFFERAD,TYPE=P 

10,1 Save record pointer 

Record updated in place 


DATASET4,(10) 

GETRTN 

* Close DCB which just 

reached EODAD 

2,DCBQUEUE+PDADCBEP-IHAPDAB 

(( 2 )) 

ZEROS(2),DCBQUEUE+PDANODCB-IHAPDAB Any DCBs left? 
GETRTN Branch if yes 


DDNAME=DDNAME1,DS0RG=PS,MACRF=GL,RECFM=FB, 
LRECL=80,E0DAD=E0DRTN,EXLST=SET3XLST 
DDNAME=DDNAME2,DS0RG=PS,MACRF=GL,RECFM=FB, 
LRECL=8 0,EODAD=EODRTN,EXLST=SET3XLST 
DDNAME=DDNAME 3,DS0RG=PS,MACRF=GMC,RECFM=FB, 
LRECL=80,EODAD=EODRTN,EXLST=SET3XLST 
DDNAME=DDNAME4,DS0RG=PS,MACRF=PM,RECFM=FB, 
LRECL=80 
MAXDCB=3 

OF'O',X'92',AL3(DCBQUEUE) 

X'0000' 

DS0RG=QS 


X 

X 

X 

X 


Note: The number of bytes required for PDAB is equal to 24 + 8n, where n is the value of the keyword, 
MAXDCB. 

Figure 19. Parallel Processing of Three Data Sets 


Following the OPEN macro, tests are made to determine whether the DCBs were 
opened for parallel processing. If not, the sequential processing routine is given 
control. 

When one or more data sets are opened for parallel processing, the get routine 
retrieves a record, saves the pointer in register 10, processes the record, and writes 
it to DATASET4. This process continues until an end-of-data condition is 
detected on one of the input data sets; the end-of-data routine locates the 
completed input data set and removes it from the queue with the CLOSE macro. 
A test is then made to determine whether any data sets remain on the queue. 
Processing continues in this manner until the queue is empty. 
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Sharing Data Sets 

There are two conditions under which a data set on a direct access device can be 
shared by two or more tasks: 

• Two or more DCBs are opened and used concurrently by the tasks to refer 
to the same, shared data set (multiple DCBs). 

• Only one DCB is opened and used concurrently by multiple tasks in a single 
job step (a single, shared DCB). 

Job control language (JCL) statements and macros are provided in the operating 
system that help you ensure the integrity of the data sets you want to share 
among the tasks that process them. Figure 20 on page 70 and Figure 21 on 
page 71 show which JCL and macros you should use, depending on the access 
method your task is using and mode of access (input, output, or update). 

Figure 20 describes the macros, JCL, and processing procedures you should use 
if more than one DCB has been opened to the shared data set. The DCBs can 
be used by tasks in the same or different job steps. 


( 
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MULTIPLE DCBs 


ACCESS MODE 

ACCESS METHOD 

BSAM,BPAM 

QSAM 

BDAM 

QISAM 

BISAM 

Input 

DISP = SHR 

DISP = SHR 

DISP = SHR 

DISP = SHR 

DISP = SHR 

Output 

No facility 

No facility 

DISP = SHR 

No facility 

DISP = SHR 
and ENQ on 
Data Set 

Update 

DISP = SHR 
user must 
ENQ on 
block 

DISP = SHR 
and Guarantee 
discrete 
blocks 

DISP = SHR 
BDAM will 
ENQ on 
block 

DISP = SHR 
and ENQ on 
data set and 
guarantee 
discrete 
blocks 

DISP = SHR 
and ENQ on 
data set and 
guarantee 
discrete 
blocks 


DISP = SHR: 

Each job step sharing an existing data set must code SHR as the subparameter of the DISP parameter 
on the DD statement for the shared data set to allow the steps to execute concurrently. For additional 
information about ensuring data set integrity, see JCL. If the tasks are in the same job step, 

DISP = SHR is not required. 

No facility: 

There are no facilities in the operating system for sharing a data set under these conditions. 

ENQ on data set: 

Besides coding DISP = SHR on the DD statement for the data set that is to be shared, each task must 
issue ENQ and DEQ macros naming the data set or block as the resource for which exclusive control 
is required. The ENQ must be issued before the GET (READ); the DEQ macro should be issued 
after the PUTX or CHECK macro that ends the operation. (For additional information on the use of 
ENQ and DEQ macros, see Supervisor Services and Macro Instructions.) 

Guarantee discrete blocks: 

When you are using the access methods that provide blocking and unblocking of records (QSAM, 
QISAM, and BISAM), it is necessary that every task updating the data set ensure that it is not 
updating a block that contains a record being updated by any other task. There are no facilities in the 
operating system for ensuring that discrete blocks are being processed by different tasks. 

ENQ on block: 

If you are updating a shared data set (specified by coding DISP = SHR on the DD statement) using 
BSAM or BPAM, your task and all other tasks must serialize processing of each block of records by 
issuing an ENQ macro before the READ macro and a DEQ macro after the CHECK macro that 
follows the WRITE macro you issued to update the record. If you are using BDAM, it provides for 
enqueuing on a block using the READ exclusive option that is requested by coding MACRF = X in 
the DCB and an X in the type operand of the READ and WRITE macros. (For an example of the 
use of the BDAM macros, see “Exclusive Control for Updating” on page 153.) 

Figure 20. JCL, Macro Instructions, and Procedures Required to Share a Data Set Using Multiple DCBs 


Figure 21 on page 71 describes the macros you can use to serialize processing of 
a shared data set when a single DCB is being shared by several tasks in a job 
step. The DISP = SHR specification on the DD statement is not required. 

Data sets can also be shared both ways at the same time. More than one DCB 
can be opened for a shared data set, while more than one task can be sharing one 
of the DCBs. Under this condition, the serialization techniques specified for 
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indexed sequential and direct data sets in Figure 20 satisfy the requirement. For 
sequential and partitioned data sets, the techniques specified in Figure 20 and 
Figure 21 must be used. 

More information on opening and closing data sets by more than one task is in 
“Opening and Closing a Data Set” on page 47. 

Shared Direct Access Storage Devices: At some installations, a direct access 
storage device is shared by two or more independent computing systems. Tasks 
executed on these systems can share data sets stored on the device. Careful 
planning should be exercised in accessing a shared data set or the same storage 
area on shared devices by multiple independent systems. Without proper 
intersystem communication, data integrity could be endangered. For details, see 
System Macros and Facilities. 


A SINGLE SHARED DCB 


ACCESS 

MODE 

ACCESS METHOD 

BSAM, 

BPAM, 

BDAM 

Create 

QSAM 

BDAM 

QISAM 

BISAM 

Input 

ENQ 

ENQ 

No action 
required 

ENQ 

ENQ 

Output 

ENQ 

ENQ 

No action 
required 

ENQ and key 
sequence 

ENQ 

Update 

ENQ 

ENQ 

No action 

ENQ 

ENQ 


ENQ: 

When a data set is being shared by two or more tasks in the same job step 
(all that use the same DCB), each task processing the data set must issue an 
ENQ macro instruction on a predefined resource name before issuing the 
macro or macros that begin the input/output operation. Each task must 
also release exclusive control by issuing the DEQ macro at the next 
sequential instruction following the input/output macro. If, however, you 
are processing an indexed sequential data set sequentially using the SETL 
and ESETL macros, you must issue the ENQ macro before the SETL 
macro and the DEQ macro after the ESETL macro. Note also that if* two 
tasks are writing different members of a partitioned data set, each task 
should issue the ENQ macro before the FIND macro and Issue the DEQ 
macro after the STOW macro that completes processing of the member. 
Additional reference information on the ENQ and DEQ macros is 
presented in Supervisor Services and Macro Instructions . For an example of 
the use of ENQ and DEQ macros with BISAM, see Figure 53 on 
page 152. 

Figure 21 (Part 1 of 2). Macro Instructions and Procedures Required to Share a Data 

Set Using a Single DCB 
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No action required: 

See “Sharing Direct Data Sets” on page 157. 

ENQ on block: 

When updating a shared BDAM data set, every task must use the BDAM 
exclusive control option that is requested by coding MACRF = X in the 
DCB macro and an X in the type operand of the READ and WRITE 
macro instructions. See “Exclusive Control for Updating” on page 153 for 
an example of the use of BDAM macros. Note that all tasks sharing a data 
set must share subpool 0 (see the ATTACH macro description in 
Supervisor Services and Macro Instructions ). 

Key sequence: 

Tasks sharing a QISAM load mode DCB must ensure that the records to 
be written are presented in ascending key sequence; otherwise, a sequence 
check will result in (1) control being passed to the SYNAD routine 
identified by the DCB, or (2) if there is no SYNAD routine, termination of 
the task. 

Figure 21 (Part 2 of 2). Macro Instructions and Procedures Required to Share a Data 

Set Using a Single DCB 


Analyzing I/O Errors 

The basic and queued access techniques both provide special macro instructions 
for analyzing input/output errors. These macro instructions can be used in 
SYNAD routines or in error analysis routines. 

SYNADAF—Perform SYNAD Analysis Function 

The SYNADAF macro analyzes the status, sense, and exceptional condition code 
data that is available to your error analysis routine. It produces an error message 
that your routine can write into any appropriate data set. The message is in the 
form of an unblocked variable-length record, but you can write it as a 
fixed-length record by omitting the block length and record length fields that 
precede the message text. 

The text of the message is 120 characters long, and begins with a field of either 36 
or 42 blanks; you can use the blank field to add your own remarks to the 
message. Following is a typical message with the blank field omitted: 

,TESTJQBb,STEP2bbb,283,TA,MASTERbb,READb,DATA CHECKbbbbb, 
0000015,BSAM 

Note: In the above example, a b indicates a blank. 

This message shows that a data check occurred during reading of the 15th block 
of a data set. The data set was identified by a DD statement named MASTER, 
and was on a magnetic tape volume on unit 283. The name of the job was 
TESTJOB; the name of the job step w;as STEP2. 
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If the error analysis routine is entered because of an input error, the first 6 bytes 
of the message (bytes 8 to 13) contain binary information. If no data was 
transmitted or if the access method is QISAM, the first 6 bytes are blanks or 
binary zeros. If the error did not prevent data transmission, the first 6 bytes 
contain the address of the input buffer and the number of bytes read. You can 
use this information to process records from the block; for example, you might 
print each record after printing the error message. Before printing the message, 
however, you should replace this binary information with EBCDIC characters. 

The SYNADAF macro provides its own save area and makes this area available 
to your error analysis routine. When used at the entry point of a SYNAD 
routine, it fulfills the routine's responsibility for providing a save area. 

SYNADRLS—Release SYNADAF Message and Save Areas 

The SYNADRLS macro releases the message and save areas provided by the 
SYNADAF macro. You must issue this macro instruction before returning from 
the error analysis routine. 

ATLAS—Perform Alternate Track Location Assignment 

The ATLAS macro lets your program recover from permanent input/output 
errors when processing a data set in direct access storage. After a data check, or 
in certain missing-address-marker conditions, you can issue ATLAS to assign an 
alternate track to replace the error track or transfer data from the error track to 
the alternate track. 

The use of this macro requires a knowledge of channel programming. A detailed 
description of the macro instruction and its use is included in System-Data 
Administration. 

If you do not use the ATLAS macro, you can use the IEHATLAS utility 
program or the Device Support Facilities program to do the same function. The 
principal difference between ATLAS and the IE HAT LAS utility program is that 
the latter provides error recovery only after your own program has been 
completed. (For a detailed description of IEHATLAS, see Utilities.) The 
INSPECT command for the Device Support Facilities program can assign 
alternate tracks. (See Device Support Facilities User's Guide and Reference.) 
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Chapter 7. DCB Exit Routines 


The DCB macro can be used to identify the location of: 

• A routine that performs end-of-data procedures 

• A routine that supplements the operating system's error recovery routine 

• A list that contains addresses of special exit routines 

The exit addresses can be specified in the DCB macro or you can complete the 
DCB fields before opening the data set. Figure 22 summarizes the exits that you 
can specify either explicitly in the DCB, or implicitly by specifying the address of 
an exit list in the DCB. 

Because OPEN/CLOSE/EOV enqueues on SYSZTIOT, functions that require 
SYSZTIOT cannot be executed in the OPEN/CLOSE/EOV exit routines. Some 
of these functions are LOCATE, OBTAIN, SCRATCH, and CATALOG. 


Exit Routine 

When Available 

Where Specified 

End-of-data-set 

When no more sequential records or blocks 
are available 

EODAD operand 

Error analysis 

After an uncorrectable input/output error 

SYNAD operand 

Block count 

After unequal block count comparison by 
end-of-volume routine 

EXLST operand and exit list 

DCB abend 

When an abend condition occurs in OPEN, 
CLOSE, or EOV routine 

EXLST operand and exit list 

DCB open 

When opening a data set 

EXLST operand and exit list 

Defer input trailer 
label 

When end-of-data is reached 

EXLST operand and exit list 

Defer nonstandard 
input trailer label 

When end-of-data is reached 

EXLST operand and exit list 

End-of-volume 

When changing volumes 

EXLST operand and exit list 

FCB image 

When opening a data set or issuing a 

SETPRT macro 

EXLST operand and exit list 

I/O error 
processing exit 

When an I/O error has occurred 

EXLST operand and exit list 


Figure 22 (Part 1 of 2). Data Management Exit Routines 
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Exit Routine 

When Available 

Where Specified 

JFCB 

When opening a data set with OPEN 

TYPE = J and RDJFCB 

EXLST operand and exit list 

JFCBE 

When opening a data set for the 3800 

EXLST operand and exit list 

Nonspecific tape 
volume mount 

When a scratch tape is requested during 

OPEN or EOV routines 

EXLST operand and exit list 

QSAM parallel 
input 

When opening a data set for QSAM 
processing 

EXLST operand and exit list 

Standard user 
label (physical 
sequential or 
direct 

organization) 

When opening, closing, or reaching the end of 
a data set, and when changing volumes 

EXLST operand and exit list 

User totaling area 

When an I/O operation is scheduled and user 
totaling has been requested 

EXLST operand and exit list 

Volume security/ 
verification 

When a scratch tape is requested during 

OPEN or EOV routines 

EXLST operand and exit list 


Figure 22 (Part 2 of 2). Data Management Exit Routines 


End-of-Data-Set Exit Routine (EODAD) 

The EODAD parameter of the DCB macro specifies the address of your 
end-of-data-set routine, which may perform any final processing on an input data 
set. This routine is entered when an FEOV macro is issued or when a CHECK 
or GET macro is issued and there are no more records or blocks to be retrieved. 
(On a READ request, this routine is entered when you issue a CHECK macro to 
check for completion of the read operation. For a BSAM data set that is opened 
for UPDAT, this routine is entered at the end of each volume. (This allows you 
to issue WRITE macros before an FEOV macro is issued.) 

The EODAD routine is not a subroutine, but rather a continuation of the 
routine that issued the CHECK, GET, or FEOV macro. After it is in your 
EODAD routine, you can continue normal processing, such as repositioning and 
resuming processing of the data set, closing the data set, or processing another 
data set. 

For BSAM, you must first reposition the data set that reached end-of-data if you 
want to issue a BSP, READ, or WRITE macro. You can reposition your data 
set by issuing a CLOSE TYPE = T macro instruction. If a READ macro is 
issued before the data set is repositioned, unpredictable results will occur. 

For BPAM, you may reposition the data set by issuing a FIND or POINT 
macro. (CLOSE TYPE = T with BPAM results in no operation performed.) 

For QISAM, you can continue processing the input data set that reached 
end-of-data by first issuing an ESETL macro to end the sequential retrieval, then 
issuing a SETL macro to set the lower limit of sequential retrieval. You can then 
issue GET macros to the data set. 
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Your task will be abnormally ended under either of the following conditions: 

• No exit routine is provided. 

• A GET macro is issued in the EODAD routine to the DCB that caused this 
routine to be entered (unless the access method is QISAM). 

When control is passed to the EODAD routine, the registers contain the 
following information: 

Register Contents 

0-1 Reserved 

2-13 Contents before execution of CHECK, GET, or FEOV macro 

instruction 

14 Address of the instruction after the last issued GET, CHECK, or 

FEOV macro 

15 Reserved 


Synchronous Error Routine Exit (SYNAD) 

The SYNAD parameter of the DCB macro specifies the address of an error 
routine that is to be given control when an input/output error occurs. This 
routine can be used to analyze exceptional conditions or uncorrectable errors. 
The block being read or written can be accepted or skipped, or processing can be 
terminated. 

If an input/output error occurs during data transmission, standard error recovery 
procedures, provided by the operating system, try to correct the error before 
returning control to your program. An uncorrectable error usually causes an 
abnormal termination of the task. However, if you specify in the DCB macro 
the address of an error analysis routine (called a SYNAD routine), the routine is 
given control if an uncorrectable error is detected. 

You can write a SYNAD routine to determine the cause and type of error that 
occurred by examining: 

• The contents of the general registers 

• The data event control block (discussed in “Accessing Data with 
READ/WRITE” on page 61) 

• The exceptional condition code 

• The standard status and sense indicators 

You can use the SYNADAF macro to perform this analysis automatically. This 
macro produces an error message that can be printed by a later PUT or WRITE 
macro. 
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After completing the analysis, you can return control to the operating system or 
close the data set. If you close the data set, note that you may not use the 
temporary close (CLOSE TYPE = T) option in the SYNAD routine. To 
continue processing the same data set, you must first return control to the control 
program by a RETURN macro. The control program then transfers control to 
your processing program, subject to the conditions described below. Never 
attempt to reread or rewrite the record, because the system has already attempted 
to recover from the error. 

When you are using GET and PUT to process a sequential data set, the 
operating system provides three automatic error options (EROPT) to be used if 
there is no SYNAD routine or if you want to return control to your program 
from the SYNAD routine: 

• ACC—accept the erroneous block 

• SKP—skip the erroneous block 

• ABE—abnormally terminate the task 

These options are applicable only to data errors, because control errors result in 
abnormal termination of the task. Data errors affect only the validity of a block 
of data. Control errors affect information or operations necessary for continued 
processing of the data set. These options are not applicable to output errors, 
except output errors on the printer. If the EROPT and SYNAD fields are not 
completed, ABE is assumed. 

If a control error or a physical I/O error is encountered for a SYSIN or SYSOUT 
dataset, the EROPT options will be ignored and the task will be abnormally 
terminated. 

You should not use the FEOV macro against the data set for which the SYNAD 
routine was entered, within the SYNAD routine. 

Because EROPT applies to a physical block of data, and not to a logical record, 
use of SKP or ACC may result in incorrect assembly of spanned records. 

When you use READ and WRITE macros, errors are detected when you issue a 
CHECK macro. If you are processing a direct or sequential data set and you 
return to the control program from your SYNAD routine, the operating system 
assumes that you have accepted the bad record. If you are creating a direct data 
set and you return to the control program from your SYNAD routine, your task 
is abnormally terminated. In the case of processing a direct data set, the return 
should be made to the control program via register 14 to make a control block 
(the IOB) available for reuse in a later READ or WRITE macro. 

For a description of the register contents on entry to your SYNAD routine, see 
the tables in Data Administration: Macro Instruction Reference . The tables there 
describe register contents for programs using QISAM, BISAM, BDAM, BPAM, 
BSAM, and QSAM. 

Your SYNAD routine can end by branching to another routine in your program, 
such as a routine that closes the data set. It can also end by returning control to 
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the control program, which then returns control to the next sequential instruction 
(after the macro) in your program. Control is not returned to the application if it 
returns to the system after a control error or physical I/O error for a SYSIN or 
SYSOUT data set. In this case, the task is abnormally terminated. If your 
routine returns control, the conventions for saving and restoring register contents 
are as follows: 

• The SYNAD routine must preserve the contents of registers 13 and 14. If 
required by the logic of your program, the routine must also preserve the 
contents of registers 2 through 12. On return to your program, the contents 
of registers 2 through 12 will be the same as on return to the control program 
from the SYNAD routine. 

• The SYNAD routine must not use the save area whose address is in register 
13, because this area is used by the control program. If the routine saves and 
restores register contents, it must provide its own save area. 

• If the SYNAD routine calls another routine or issues supervisor or data 
management macros, it must provide its own save area or issue a SYNADAF 
macro. The SYNADAF macro provides a save area for its own use, and 
then makes this area available to the SYNAD routine. Such a save area 
must be removed from the save area chain by a SYNADRLS macro before 
control is returned to the control program. 

If the error analysis routine receives control from the close routine when indexed 
sequential data sets are being created (the DCB is opened for QISAM load 
mode), bit 3 of the IOBFLAGS field in the load mode buffer control table 
(IOBBCT) is set to 1. The DCBWKPT6 field in the DCB contains an address 
of a list of work area pointers (ISLVPTRS). The pointer to the IOBBCT is at 
offset 8 in this list as shown in the following diagram: 



If the error analysis routine receives control from the CLOSE routine when 
indexed sequential data sets are being processed using QISAM scan mode, bit 2 


of the DCB field DCBEXCD2 is set to 1. 
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Exit List (EXLST) 




The EXLST parameter of the DCB macro specifies the address of a list that 
contains the addresses of special processing routines, a forms control buffer 
(FCB) image, or a user totaling area. An exit list must be created if user label, 
data control block, end-of-volume, block count, JFCBE, or DCB abend exits are 
used, or if a PDAB macro or FCB image is defined in the processing program. 

The exit list is built of 4-byte entries that must be aligned on fullword 
boundaries. Each exit list entry is identified by a code in the high-order byte, and 
the address of the routine, image, or area is specified in the 3 low-order bytes. 
Codes and addresses for the exit list entries are shown in Figure 23. 


Entry Type 

Hex 

Code 

3-Byte Address—Purpose 

Inactive entry 

00 

Ignore the entry; it is not 
active. 

Input header label exit 

01 

Process a user input 
header label. 

Output header label exit 

02 

Create a user output 
header label. 

Input trailer label exit 

03 

Process a user input trailer 
label. 

Output trailer label exit 

04 

Create a user output 
trailer label. 

Data control block exit 

05 

Take a data control block 
exit. 

End-of-volume exit 

06 

Take an end-of-volume 
exit. 

JFCB exit 

07 

JFCB address for 

RDJFCB and OPEN 

TYPE = J SVCs. 


08 

Reserved. 


09 

Reserved. 

User totaling area 

0A 

Address of beginning of 
user's totaling area. 

Block count exit 

0B 

Take a 

block-count-unequal exit. 

Defer input trailer label. 

OC 

Defer processing of a user 
input trailer label from 
end-of-data until closing. 

Defer nonstandard input 
trailer label 

0D 

Defer processing a 
nonstandard input trailer 
label on magnetic tape 
unit from end-of-data 
until closing (no exit 
routine address). 


Figure 23 (Part 1 of 2). DCB Exit List Format and Contents 
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Entry Type 

Hex 

Code 

3-Byte Address—Purpose 


0E-0F 

Reserved. 

FCB image 

10 

Define an FCB image. 

DCB abend exit 

11 

Examine the abend 
condition and select one 
of several options. 

QSAM parallel input 

12 

Address of the PDAB for 
which this DCB is a 
member. 


13-14 

Reserved. 

JFCBE exit 

15 

Take an exit during 

OPEN to allow user to 
examine JCL= specified 
setup requirements for a 

3800 printer. 


16 

Reserved. 

OPEN/EOV nonspecific 
tape volume mount 

17 

Option to specify a tape 
volume serial number. 

OPEN/EOV volume 
security/verification 

18 

Verify a tape volume and 
some security checks. 


19-7F 

Reserved. 

Last entry 

80 

Treat this entry as the last 
entry in the list. This 
code can be specified with 
any of the above but must 
always be specified with 
the last entry exit routine. 


Figure 23 (Part 2 of 2). DCB Exit List Format and Contents 

You can activate or deactivate any entry in the list by placing the required code 
in the high-order byte. Care must be taken, however, not to destroy the last 
entry indication. The operating system routines scan the list from top to bottom, 
and the first active entry found with the proper code is selected. 

You can shorten the list during execution by setting the high-order bit to 1, and 
extend it by setting the high-order bit to 0. 
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When control is passed to an exit routine, the registers contain the following 

information: 

Register Contents 

0 Variable; see exit routine description. 

1 The 3 low-order bytes contain the address of the DCB currently being 

processed, except when the user-label exits (X'OL-X'04'), user totaling 
exit (X'OA'), DCB abend exit (XTT), nonspecific tape volume mount 
exit (XT T), or the tape volume security/verification exit (XT 8') is 
taken, when register 1 contains the address of a parameter list. The 
contents of the parameter list are described in the explanation of each 
exit routine. 

2-13 Contents before execution of the macro. 

14 Return address (must not be altered by the exit routine). 

15 Address of exit routine entry point. 

The conventions for saving and restoring register contents are as follows: 

• The exit routine must preserve the contents of register 14. It need not 
preserve the contents of other registers. The control program restores the 
contents of registers 2 to 13 before returning control to your program. 

• The exit routine must not use the save area whose address is in register 13, 
because this area is used by the control program. If the exit routine calls 
another routine or issues supervisor or data management macros, it must 
provide the address of a new save area in register 13. 

• The DCBOFUEX bit in the DCBOFLGS is set to zero when a user exit is 
taken. This restricts the use of certain macros (for example, CLOSE) in an 
exit routine. 


Standard User Label Exit 

When you create a data set with physical sequential or direct organization, you 
can provide routines to create your own data set labels. You can also provide 
routines to verify these labels when you use the data set as input. Each label is 
80 characters long, with the first 4 characters UHL1,UHL2,...,UHL8 for a header 
label or UTL1,UTL2,...,UTL8 for a trailer label. User labels are not allowed on 
indexed sequential, data sets. 

The physical location of the labels on the data set depends on the data set 
organization. For direct (BDAM) data sets, user labels are placed on a separate 
user label track in the first volume. User label exits are taken only during 
execution of the OPEN and CLOSE routines. Thus you may create or examine 
as many as eight user header labels only during execution of OPEN and as many 
as eight trailer labels only during execution of CLOSE. Because the trailer labels 
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are on the same track as the header labels, the first volume of the data set must 
be mounted when the data set is closed. 

For physical sequential (BSAM or QSAM) data sets, you may create or examine 
as many as eight header labels and eight trailer labels on each volume of the data 
set. For ASCII tape data sets, you may create an unlimited number of user 
header and trailer labels. The user label exits are taken during OPEN, close, and 
end-of-volume processing. 

To create or verify labels, you must specify the addresses of your label exit 
routines in an exit list as shown in Figure 23 on page 80. Thus you may have 
separate routines for creating or verifying header and trailer label groups. Care 
must be taken if a magnetic tape is read backward, because the trailer label group 
is processed as header labels and the header label group is processed as trailer 
labels. 

When your routine receives control, the contents of register 0 are unpredictable. 
Register 1 contains the address of a parameter list. The contents of registers 2 to 
13 are the same as when the macro instruction was issued. However, if your 
program does not issue the CLOSE macro, or abnormally ends before issuing 
CLOSE, the CLOSE macro will be issued by the control program, with 
control-pro gram information in these registers. 

The parameter list pointed to by register 1 is a 16-byte area aligned on a fullword 
boundary. Figure 24 shows the contents of the area. 


WMb 

Address of 80-byte label buffer area 

i i 


Address of DCB being processed 

i i 

//^Error f 1 ags 

Address of status information 

1 1 


Address of user totaling image area 

-1_1_ 


Figure 24. Parameter List Passed to User Label Exit Routine 


The first address in the parameter list points to an 80-byte label buffer area. For 
input, the control program reads a user label into this area before passing control 
to the label routine. For output, the user label exit routine builds labels in this 
area and returns to the control program, which writes the label. When an input 
trailer label routine receives control, the EOF flag (high-order byte of the second 
entry in the parameter list) is set as follows: 

Bit 0=0: Entered at end-of-volume 
Bit 0=1: Entered at end-of-file 
Bits 1-7: Reserved 

When a user label exit routine receives control after an uncorrectable I/O error 
has occurred, the third entry of the parameter list contains the address of the 
standard status information. The error flag (high-order byte of the third entry in 
the parameter list) is set as follows: 
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Bit 0=1: Uncorrectable I/O error 

Bit 1=1: Error occurred during writing of updated label 
Bits 2-7: Reserved 

The fourth entry in the parameter list is the address of the user totaling image 
area. This image area is the entry in the user totaling save area that corresponds 
to the last record physically written on the volume. (The image area is discussed 
further under “User Totaling (BSAM and QSAM only)” on page 86.) 

Each routine must create or verify one label of a header or trailer label group, 
place a return code in register 15, and return control to the operating system. 

The operating system responds to the return code as shown in Figure 25. 

You can create user labels only for data sets on magnetic tape volumes with IBM 
standard labels or ISO/ANSI/FIPS labels and for data sets on direct access 
volumes. When you specify both user labels and IBM standard labels in a DD 
statement by specifying LABEL = (,SUL) and there is an active entry in the exit 
list, a label exit is always taken. Thus, a label exit is taken even when an input 
data set does not contain user labels, or when no user label track has been 
allocated for writing labels on a direct access volume. In either case, the 
appropriate exit routine is entered with the buffer area address parameter set to 0. 
On return from the exit routine, normal processing is resumed; no return code is 
necessary. 



Routine Type Return Code 

Input header or 0 (X'00') 

trailer label 

4 (X'04') 

8 1 (xm') 

12 1 (X'OC') 

Output header or 0 (X'00') 

trailer label 

4 (X'04') 


System Response 

Normal processing is resumed. If 
there are any remaining labels in the 
label group, they are ignored. 

The next user label is read into the 
label buffer area and control is 
returned to the exit routine. If there 
are no more labels in the label 
group, normal processing is resumed. 
The label is written from the label 
buffer area and normal processing is 
resumed. 

The label is written from the label 
area, the next label is read into the 
label buffer area, and control is 
returned to the label processing 
routine. If there are no more labels, 
processing is resumed. 

Normal processing is resumed; no 
label is written from the label buffer 
area. 

User label is written from the label 
buffer area. Normal processing is 
resumed. 


Figure 25 (Part 1 of 2). System Response to a User Label Exit Routine Return Code 


(f ^ 
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Routine Type 


Return Code System Response 


8 (X'08') User label is written from the label 

buffer area. If fewer than eight labels 
have been created, control is 
returned to the exit routine, which 
then creates the next label. If eight 
labels have been created, normal 
processing is resumed. 


Figure 25 (Part 2 of 2). System Response to a User Label Exit Routine Return Code 

Note to Figure 25 

1 Your input label routines can return these codes only when you are 

processing a physical sequential data set opened for UPDAT or a direct data 
set opened for OUTPUT or UPDAT. These return codes allow you to 
verify the existing labels, update them if necessary, then request that the 
system write the updated labels. 

Label exits are not taken for system output (SYSOUT) data sets, or for data sets 

on volumes that do not have standard labels. For other data sets, exits are taken 

as follows: 

• When an input data set is opened, the input header label exit 01 is taken. If 
the data set is on tape being opened for RDBACK, user trailer labels will be 
processed. 

• When an output data set is opened, the output header label exit 02 is taken. 
However, if the data set already exists and DISP= MOD is coded in the DD 
statement, the input trailer label exit 03 is taken to process any existing trailer 
labels. If the input trailer label exit 03 does not exist, then the deferred input 
trailer label exit 0C is taken if it exists; otherwise, no label exit is taken. For 
tape, these trailer labels will be overwritten by the new output data or by 
EOV or close processing when writing new standard trailer labels. For direct 
access devices, these trailer labels will still exist unless rewritten by EOV or 
close processing in an output trailer label exit. 

• When an input data set reaches end-of-volume, the input trailer label exit 03 
is taken. If the data set is on tape opened for RDBACK, header labels will 
be processed. The input trailer label exit 03 is not taken if you issue an 
FEOV macro. If a defer input trailer label exit 0C is present, and an input 
trailer label exit 03 is not present, the 0C exit is taken. After switching 
volumes, the input header label exit 01 is taken. If the data set is on tape 
opened for RDBACK, trailer labels will be processed. 

• When an output data set reaches end-of-volume, the output trailer label exit 
04 is taken. After switching volumes, output header label exit 02 is taken. 

• When an input data set reaches end-of-data, the input trailer label exit 03 is 
taken before the EODAD exit, unless the DCB exit list contains a defer input 
trailer label exit 0C. 
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• When an input data set is closed, no exit is taken unless the data set was 
previously read to end-of-data and the defer input trailer label exit OC is 
present. If so, the defer input trailer label exit OC is taken to process trailer 
labels, or if the tape is opened for RDBACK, header labels. 

• When an output data set is closed, the output trailer label exit 04 is taken. 

To process records in reverse order, a data set on magnetic tape can be read 
backward. When you read backward, header label exits are taken to process 
trailer labels, and trailer label exits are taken to process header labels. The system 
presents labels from a label group in ascending order by label number, which is 
the order in which the labels were created. If necessary, an exit routine can 
determine label type (UHL or UTL) and number by examining the first four 
characters of each label. Tapes with IBM standard labels and direct access 
devices can have as many as eight user labels. Tapes with ISO/ANSI/FIPS labels 
can have an unlimited number of user labels. 

If an uncorrectable error occurs during reading or writing of a user label, the 
system passes control to the appropriate exit routine, with the third word of the 
parameter list flagged and pointing to status information. 

After an input error, the exit routine must return control with an appropriate 
return code (0 or 4). No return code is required after an output error. If an 
output error occurs while the system is opening a data set, the data set is not 
opened (DCB is flagged) and control is returned to your program. If an output 
error occurs at any other time, the system attempts to resume normal processing. 


User Totaling (BSAM and QSAM only) 

When creating or processing a data set with user labels, you may develop control 
totals for each volume of the data set and store this information in your user 
labels. For example, a control total that was accumulated as the data set was 
created can be stored in your user label and later compared with a total 
accumulated during processing of the volume. User totaling helps you by 
synchronizing the control data you create with records physically written on a 
volume. For an output data set without user labels, you can also develop a 
control total that will be available to your end-of-volume routine. 

To request user totaling, you must specify OPTCD = T in the DCB macro 
instruction or in the DCB parameter of the DD statement. The area in which 
you collect the control data (the user totaling area) must be identified to the 
control program by an entry of hexadecimal 0A in the DCB exit list. 

OPTCD = T cannot be specified for SYSIN or SYSOUT data sets. 

The user -totaling area, an area in storage that you provide, must begin on a 
halfword boundary and be large enough to contain your accumulated data plus a 
2-byte length field. The length field must be the first 2 bytes of the area and 
specify the length of the complete area. A data set for which you have specified 
user totaling (OPTCD = T) will not be opened if either the totaling area length or 
the address in the exit list is 0, or if there is no X'OA' entry in the exit list. 


86 MVS/XA Data Administration Guide 




The control program establishes a user totaling save area, where the control 
program preserves an image of your totaling area, when an I/O operation is 
scheduled. When the output user label exits are taken, the address of the save 
area entry (user totaling image area) corresponding to the last record physically 
written on a volume is passed to you in the fourth entry of the user label 
parameter list. (This parameter list is described in “Standard User Label Exit” on 
page 82.) When an end-of-volume exit is taken for an output data set and user 
totaling has been specified, the address of the user totaling image area is in 
register 0. 

When using user totaling for an output data set, that is, when creating the data 
set, you must update your control data in your totaling area before issuing a 
PUT or a WRITE macro. The control program places an image of your totaling 
area in the user totaling save area when an I/O operation is scheduled. A pointer 
to the save area entry (user totaling image area) corresponding to the last record 
physically written on the volume, is passed to you in your label processing 
routine. Thus you can include the control total in your user labels. When 
subsequently using this data set for input, you can collect the same information 
as you read each record and compare this total with the one previously stored in 
the user trailer label. If you have stored the total from the preceding volume in 
the user header label of the current volume, you can process each volume of a 
multivolume data set independently and still maintain this system of control. 

When variable-length records are specified with the totaling function for user 
labels, special considerations are necessary. Because the control program 
determines whether a variable-length record will fit in a buffer after a PUT or a 
WRITE has been issued, the total you have accumulated may include one more 
record than is really written on the volume. For variable-length spanned records, 
the accumulated total will include the control data from the volume-spanning 
record although only a segment of the record is on that volume. However, when 
you process such a data set, the volume-spanning record or the first record on the 
next volume will not be available to you until after the volume switch and user 
label processing are completed. Thus the totaling information in the user label 
may not agree with that developed during processing of the volume. 

One way you can resolve this situation is to maintain, when you are creating a 
data set, control data pertaining to each of the last two records and include both 
totals in your user labels. Then the total related to the last complete record on 
the volume and the volume-spanning record or the first record on the next 
volume would be available to your user label routines. During subsequent 
processing of the data set, your user label routines can determine if there is 
agreement between the generated information and one of the two totals 
previously saved. 

When the totaling function for user labels is selected with DASD devices and 
secondary space is specified, the total accumulated may be one less than the 
actual written. 
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Data Control Block Open Exit 


You can specify in an exit list the address of a routine that completes or modifies 
a DCB and does any additional processing required before the data set is 
completely open. The routine is entered during the opening process after the 
JFCB has been used to supply information for the DCB. The routine can 
determine data set characteristics by examining fields completed from the data set 
labels. When your DCB exit routine receives control, the 3 low-order bytes of 
register 1 will contain the address of the DCB currently being processed. 

As with label processing routines, the contents of register 14 must be preserved 
and restored if any macros are used in the routine. Control is returned to the 
operating system by a RETURN macro; no return code is required. 

This exit is mutually exclusive with the JFCBE exit. If you need both the 
JFCBE and data control block OPEN exits, you must use the JFCBE exit to 
pass control to your routines. 

The DCB OPEN exit is intended for modifying or updating the DCB. System 
functions should not be attempted in this exit prior to returning to OPEN 
processing; in particular, dynamic allocation, OPEN, CLOSE, EOV, and 
DADSM functions should not be invoked because of an existing OPEN enqueue 
on the SYSZTIOT resources. 


Open/EOV Nonspecific Tape Volume Mount Exit 

This user exit gives you the option of identifying a specific tape volume to be 
requested in place of a nonspecific (scratch) tape volume. A XT T in the DCB 
exit list (EXLST) activates this exit. (See “Exit List (EXLST)” on page 80 for 
more information about EXLST.) This exit, which supports only IBM standard 
labeled tapes, was designed to be used with the Open/EOV volume security and 
verification user exit. However, this exit can be used by itself. 

Open or end-of-volume (EOV) calls this exit when either must issue mount 
message IEC501A or EIC501E to request a scratch tape volume. Open issues the 
mount message if you specify the DEFER parameter with the UNIT option, and 
you either didn't specify a volume serial number in the DD statement or you 
specified ? VOL= SER = SCRTCH f . EOV always calls this exit for a scratch 
tape volume request. 

This user exit gets control in the key and state of the program that issued the 
OPEN or EOV, and no locks are held. After you are in control, you must 
provide a return code in register 15. 
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Return Code Meaning 

00 (X'00') Continue with the scratch tape request as if this exit had 
not been called. 

04 (X'04') Replace the scratch tape request with a specific volume 
serial number. Do this by loading the address of a 
6-byte volume serial number into register 0. 

Note: A value other than 0 or 4 in register 15 is treated as a 0. 

If OPEN or EOV finds that the volume pointed to by register 0 is being used 
either by this or by another job (an active ENQ on this volume), it takes this exit 
again and continues to do so until you either specify another volume serial 
number or request a scratch volume. If the volume you specify is available but is 
rejected by OPEN or EOV for some reason (I/O errors, expiration date, 
password check, and so forth), this exit is not taken again. 

When this exit gets control, register 1 points to the parameter list described by the 
IECOENTE macro. Figure 26 shows this parameter list. 


+ 

OENTID 

DS 

CL4 

PLIST ID ('OENT') 

+ 

OENTFLG 

DS 

X 

FLAG BYTES 

+ 

OENTOEOV 

EQU 

X 1 80' 

0=OPEN, l=EOV 

+ 

OENTNTRY 

EQU 

X'01' 

0=1ST ENTRY ,^SUBSEQUENT ENTRY 

+ 

OENTOPTN 

DS 

X 

OPEN OPTION (OUTPUT/INPUT/...) 

+ 

OENTMASK 

EQU 

X'OF' 

TO MASK OFF UNNECESSARY BITS 

+ 

OENTRSVD 

DS 

XL2 

RESERVED 

-h 

OENTDCBA 

DS 

A 

ADDRESS OF USER DCB 

+ 

OENTVSRA 

DS 

A 

ADDRESS OF VOLSER 

+ 

OENTJFCB 

DS 

A 

ADDRESS OF 0/C/E COPY OF JFCB 

+ 

OENTLENG 

EQU 

*-&L 

PLIST LENGTH 

+ 

OENTREGS 

DS 

6F 

REGISTER SAVE AREA 

+ 

OENTAREA 

EQU 

*-0ENTE 

MACRO LENGTH 


Figure 26. IECOENTE Macro Parameter List 


OENTOEOV 

set to 0 if OPEN called this exit; set to 1 if EOV called this exit. 

OENTNTRY 

set to 1 if this is not the first time this exit was called because the requested 
tape volume is being used by this or any other job. 

OENTOPTN 

contains the OPEN options from the DCB parameter list (OUTPUT, 
INPUT, OUTIN, INOUT, and so forth). For EOV processing, the 
options byte in the DCB parameter list indicates how EOV is processing 
this volume. For example, if you open a tape volume for INOUT and 
EOV is called during an input operation on this tape volume, the DCB 
parameter list and OENTOPTN are set to indicate INPUT. 
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OENTVSRA 

points to the last volume serial number you requested in this exit but was 
in use either by this or another job. OENTVSRA is set to 0 the first time 
this exit is called. 

OENTJFCB 

points to the OPEN or EOV copy of the JFCB. The high order bit is 
always on, indicating that this is the end of the parameter list. 

OENTREGS 

starts the register save area used by OPEN or EOV. Do not use this save 
area in this user exit. 



Convention for Saving and Restoring General Registers 

When this user exit is entered, the general registers contain: 

Register C on ten ts 

0 Variable 

1 Address of the parameter list for this exit 

2-13 Contents of the registers before the OPEN or EOV was 

issued 

14 Return address (you must preserve the contents of this 
register in this user exit) 

15 Entry point address to this user exit 

You do not have to preserve the contents of any register other than register 14. 

The operating system restores the contents of registers 2 through 13 before it 
returns to OPEN or EOV and before it returns control to the original calling 
program. 

Do not use the save area pointed to by register 13; the operating system uses it. 
If you call another routine, or issue a supervisor or data management macro in 
this user exit, you must provide the address of a new save area in register 13. 


Open/EOV Volume Security and Verification Exit 

This user exit lets you verify that the volume that is currently mounted is the one 
you want. You can also use it to bypass the OPEN or EOV expiration date, 
password, and data set name security checks. A XT 8' in the DCB exit list 
(EXLST) activates this exit. (See “Exit List (EXLST)” on page 80 for more 
information about EXLST.) This exit, which supports IBM standard label tapes, 
was designed to be used with the OPEN/EOV nonspecific tape volume mount 
user exit. (See “Open/EOV Nonspecific Tape Volume Mount Exit” on page 88 
for more information about that user exit.) How r ever, this exit can be used by 
itself. 

Note: This exit is available only for APF-authorized programs. 
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This user exit gets control in the key and state of the program that issued the 
OPEN or EOV request, and no locks are held. After you are in control, you 
must provide a return code in register 15. 

Return Code Meaning 


00 (X'00') Use this tape volume. Return to OPEN or EOV as if 
this exit had not been called. 

04 (X / 04 / ) Reject this volume and: 

• Output 

— If the data set is the first data set on the volume, 
request a scratch tape. This causes OPEN or 
EOV to issue demount message IEC502E for 
the rejected tape volume, and mount message 
IEC501A for a scratch tape volume. If the 
nonspecific tape volume mount exit is active, it 
is called. 

— If the data set is other than the first one on the 
volume, process this return code as if it were 
return code 08. 


• Input 

— Treat this return code as if it were return code 
08. 

08 (X'08') Abnormally terminate OPEN or EOV unconditionally; 
no scratch tape request is issued. 

Open abnormally terminates with a 913-34 abend code, 
and EOV terminates with a 937-29 abend code. 

12 (X'OC') Use this volume without checking the data set's 

expiration date, but check its password and name. If the 
expiration date of the current data set is in effect, the 
new data set can still write over it. 

16 (XT0') Use this volume. A conflict with the password, label 
expiration date, or data set name does not prevent the 
new data set from writing over the current data set if it 
is the first one on the volume. To write over other than 
the first data set, the new data set must have the same 
level of security protection as the current data set. 


When this exit gets control, register 1 points to the parameter list described by the 
IECOEVSE macro. The parameter list appears as: 
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+ 

OEVSID 

DS 

CL4 

ID FIELD = OEVS 

+ 

OEVSFLG 

DS 

X 

FLAGS BYTE 

4- 

OEVSEOV 

EQU 

X'80' 

0=0PEN, 1=E0V 

+ 

OEVSFILE 

* 

EQU 

X'01' 

0=1ST FILE, 1=SUBSEQ FILE 

BITS 1 THROUGH 6 RESERVED 

+ 

OEVSOPTN 

DS 

X 

OPEN OPTION (OUTPUT/INPUT/...) 

+ 

OEVSMASK 

EQU 

X'OF’ 

MASK 

4- 

OEVSRSVD 

DS 

XL2 

RESERVED 

4* 

OEVSDCBA 

DS 

A 

ADDRESS OF USER DCB 

4- 

OEVSVSRA 

DS 

A 

ADDRESS OF 6-BYTE VOLSER 

+ 

0EVSHDR1 

DS 

A 

ADDRESS OF HDR1/E0F1 

4- 

OEVSJFCB 

DS 

A 

ADDRESS OF 0/C/E COPY OF JFCB 

+ 

OEVSLENG 

EQU 

*-&L 

PLIST LENGTH 

4- 

OEVSREGS 

DS 

6F 

REGISTER SAVE AREA 

4- 

OEVSAREA 

EQU 

*-OEVSE 

MACRO LENGTH 


Figure 27. IECOEVSE Macro Parameter List 


OEVSFLG 

a flag field containing two flags. 

OEVSEOV is set to 0 if OPEN called this exit; set to 1 if EOV called this 
exit. 

OEVSFILE is set to 0 if the first data set on the volume is to be written; 
set to 1 if this is not the first data set on the volume to be written. This bit 
is always 0 for INPUT processing. 

OEVSOPTN 

a 1-byte field containing the OPEN options from the DCB parameter list 
(OUTPUT, INPUT, INOUT, and so forth). For EOV processing, this 
byte indicates how EOV is processing this volume. For example, if you 
opened a tape volume for OUTIN and EOV is called during an output 
operation on the tape volume, the DCB parameter list and OEVSOPTN 
are set to indicate OUTPUT. 

OEVSVSRA 

a pointer to the current volume serial number that OPEN or EOV is 
processing. 

OEVSHDR1 

a pointer to a HDR1 label, if one exists; or an EOF1 label, if you are 
creating other than the first data set on this volume. 

OEVSJFCB 

a pointer to the OPEN, CLOSE, or EOV copy of the JFCB. The 
high-order bit is always on, indicating that this is the end of the parameter 
list. 

OEVSREGS 

a register save area used by OPEN or EOV. Do not use this save area in 
this user exit. 
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Convention for Saving and Restoring General Registers 


When this user exit is entered, the general registers contain: 

Register Contents 

0 Variable 

1 Address of the parameter list for this exit. 

2-13 Contents of the registers before the OPEN or EOV was 

issued 

14 Return address (you must preserve the contents of this 
register in this user exit) 

15 Entry point address to this user exit 

You do not have to preserve the contents of any register other than register 14. 

The operating system restores the contents of registers 2 through 13 before it 
returns to OPEN or EOV and before it returns control to the original calling 
program. 

Do not use the save area pointed to by register 13; the operating system uses it. 
If you call another routine or issue a supervisor or data management macro in 
this user exit, you must provide the address of a new save area in register 13. 


QSAM Parallel Input Exit 

A request for parallel input processing is indicated by including the address of a 
parallel data access block (PDAB) in the DCB exit list. The address must be on 
a fullword boundary with the first byte of the entry containing XT 2' or, if it is 
the last entry, X , 92 / . For more information on parallel input processing, see 
“Parallel Input Processing (QSAM Only)” on page 66. 


JFCBE Exit 


JCL-specified setup requirements for the IBM 3800 Printing Subsystem cause a 
JFCB extension (JFCBE) to be created to reflect those specifications. A JFCBE 
exists if BURST, MODIFY, CHARS, FLASH, or any copy group is coded on 
the DD statement. The JFCBE exit can be used to examine or modify those 
specifications in the JFCBE. The address of the routine should be placed in an 
exit list. (The device allocated does not have to be a 3800.) This exit is taken 
during OPEN processing and is mutually exclusive with the data control block 
exit. If you need both the JFCBE and data control block exits, you must use the 
JFCBE exit to pass control to your routines. 

With a 3800, when you issue the SETPRT macro to a SYSOUT data set, the 
JFCBE is further updated from the information in the SETPRT parameter list. 

When control is passed to your exit routine, the contents of register 1 will be the 
address of the DCB being processed. 

The area pointed to by register 0 will also contain the 4-byte FCB identification 
that is obtained from the JFCB. The FCB identification is placed in the 4 bytes 
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following the 176-byte JFCBE. If the FCB operand was not coded on the DD 
statement, this FCB field will be binary zeros. ^ 

If your copy of the JFCBE is modified during an exit routine, you should 
indicate this fact by turning on bit JFCBEOPN (X'80' in JFCBFLAG) in the 
JFCBE copy. On return to OPEN, this bit indicates whether the system copy is 
to be updated. The 4-byte FCB identification in your area will be used to update 
the JFCB regardless of the bit setting. Checkpoint/restart also interrogates this 
bit to determine which version of the JFCBE will be used at restart time. If this 
bit is not on, the JFCBE generated by the restart JCL will be used. 


End-of-Volume Exit 

You can specify in an exit list the address of a routine that is entered when 
end-of-volume is reached in processing of a physical sequential data set. 

When you concatenate data sets with unlike attributes, no EOV exits are taken. 

When the end-of-volume routine is entered, register 0 contains 0 unless user 
totaling was specified. If you specified user totaling in the DCB macro (by 
coding OPTCD = T) or in the DD statement for an output data set, register 0 
contains the address of the user totaling image area. The routine is entered after 
a new volume has been mounted and all necessary label processing has been 
completed. If the volume is a reel of magnetic tape, the tape is positioned after 
the tapemark that precedes the beginning of the data. 

You can use the end-of-volume (EOV) exit routine to take a checkpoint by 
issuing the CHKPT macro, which is discussed in Checkpoint!Restart. If a 
checkpointed job step terminates abnormally, it can be restarted from the EOV 
checkpoint. When the job step is restarted, the volume is mounted and 
positioned as upon entry to the routine. Restart becomes impossible if changes 
are made to the link pack area (LPA) library between the time the checkpoint is 
taken and the time the job step is restarted. When the step is restarted, pointers 
to end-of-volume modules must be the same as when the checkpoint was taken. 

The end-of-volume exit routine returns control in the same manner as the data 
control block exit routine. The contents of register 14 must be preserved and 
restored if any macros are used in the routine. Control is returned to the 
operating system by a RETURN macro; no return code is required. 


Block Count Exit 


You can specify in an exit list the address of a routine that will allow you to 
abnormally terminate the task or continue processing when the end-of-volume 
routine finds an unequal block count condition. When you are using standard 
labeled input tapes, the block count in the trailer label is compared by the 
end-of-volume routine with the block count in the DCB. The count in the trailer 
label reflects the number of blocks written when the data set was created. The 
number of blocks read when the tape is used as input is contained in the 
DCBBLKCT field of the DCB. 
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The routine is entered during end-of-volume processing. The trailer label block 
count is passed in register 0. You may gain access to the count field in the DCB 
by using the address passed in register 1 plus the proper displacement, as 
explained in Debugging Handbook. If the block count in the DCB differs from 
that in the trailer label when no exit routine is provided, the task is abnormally 
terminated. The routine must terminate with a RETURN macro and a return 
code that indicates what action is to be taken by the operating system, as shown 
in Figure 28. As with other exit routines, the contents of register 14 must be 
saved and restored if any macros are used. 


Return Code System Action 

0 (X'OQ') The task is to be abnormally terminated. 

4 (X / 04 / ) Normal processing is to be resumed. 

Figure 28. System Response to Block Count Exit Return Code 


Defer Nonstandard Input Trailer Label Exit 

In an exit list, you can specify a code that indicates that you want to defer 
nonstandard input trailer label processing from end-of-data until the data set is 
closed. The address portion of the entry is not used by the operating system. 

An end-of-volume condition exists in several situations. Two examples are: (1) 
when the system reads a filemark or a tapemark at the end of a volume of a 
multivolume data set but that volume is not the last, and (2) when the system 
reads a filemark or a tapemark at the end of a data set. The first situation is 
referred to here as an end-of-volume condition, and the second as an end-of-data 
condition, although it, too, can occur at the end of a volume. 

For an end-of-volume (EOV) condition, the EOV routine passes control to your 
nonstandard input trailer label routine, whether or not this exit code is specified. 
For an end-of-data condition when this exit code is specified, the EOV routine 
does not pass control to your nonstandard input trailer label routine. Instead, the 
close routine passes control to your end-of-data routine. 


FCB Image Exit 


You can specify in an exit list the address of a forms control buffer (FCB) image. 
This FCB image can. be loaded into the forms control buffer of the printer 
control unit. The FCB controls the movement of forms in printers that do not 
use a carriage control tape. 

Multiple exit list entries in the exit list can define FCBs. The OPEN and 
SETPRT routines search the exit list for requested FCBs before searching 
SYS 1 .IMAGELIB. 
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The first 4 bytes of the FCB image contain the image identifier. To load the 
FCB, this image identifier is specified in the FCB parameter of the DD 
statement, by the SETPRT macro, or by the system operator in response to 
message IEC127D or IEC129D. 

For an IBM 3203 or 3211 Printer, the image identifier is followed by the FCB 
image described in System-Data Administration. For a 3800 FCB image, see 
IBM 3800 Printing Subsystem Programmer's Guide. 

You can use an exit list to define an FCB image only when writing to an online 
printer. Figure 29 illustrates one way the exit list can be used to define an FCB 
image. 


DCB 


..,EXLST=EXLIST 


EXLIST 


FCBIMG 


DS 

DC 

DC 

DC 

DC 

DC 

DC 

DC 


OF 

X’lO' 

AL3(FCBIMG) 
X’80000000* 
CL4'IMG1' 

x'oo' 

AL1(67) 

X 90 


* 16 line character positions to the right 


Flag code for FCB image 

Address of FCB image 

End of EXLST and a null entry 

FCB identifier 

FCB is not a default 

Length of FCB 

Offset print line 


//ddname 

/* 


DC 

X'OO' 

Spacing is 6 lines per inch 


DC 

5X'00' 

Lines 2-6, no channel codes 


DC 

X'01' 

Line 7, channel 1 


DC 

6X* 00' 

Lines 8-13, no channel codes 


DC 

X'02' 

Line (or Lines) 14, channel 2 


DC 

5X’00' 

Line (or Lines) 15-19, no channel 

codes 

DC 

X'03' 

Line (or Lines) 20, channel 3 


DC 

9X'00' 

Line (or Lines) 21-29, no channel 

codes 

DC 

X'04' 

Line (or Lines) 30, channel 4 


DC 

19X'00' 

Line (or Lines) 31-49, no channel 

codes 

DC 

X 1 05' 

Line (or Lines) 50, channel 5 


DC 

X' 06' 

Line (or Lines) 51, channel 6 


DC 

X 1 07 1 

Line (or Lines) 52, channel 7 


DC 

X'08' 

Line (or Lines) 53, channel 8 


DC 

X 1 09 1 

Line (or Lines) 54, channel 9 


DC 

X'OA' 

Line (or Lines) 55, channel 10 


DC 

X'OB' 

Line (or Lines) 56, channel 11 


DC 

X'OC' 

Line (or Lines) 57, channel 12 


DC 

8X 1 00' 

Line (or Lines) 58-65, no channel 

codes 

DC 

X’ 10' 

End of FCB image 


END 

DD 

UNIT=3211 

,FCB=(IMG1,VERIFY) 



Figure 29. Defining an FCB Image for a 3211 


96 MVS/XA Data Administration Guide 




DCB Abend Exit 


The DCB abend exit is provided to give you some options regarding the action 
you want the system to take when a condition arises that may result in abnormal 
termination of your task. This exit can be taken any time an abend condition 
arises during the process of opening, closing, or handling an end-of-volume 
condition for a DCB associated with your task. 

When an abend condition arises, a write-to-programmer message about the abend 
is issued and your DCB abend exit is given control, provided there is an active 
DCB abend exit routine address in the DCB being processed. If STOW called 
the end-of-volume routines to get secondary space to write an end-of-file mark 
for a partitioned data set, or it' the DCB being processed is for an indexed 
sequential data set, the DCB abend exit routine will not be given control it' an 
abend condition occurs. The contents of the registers when your exit routine is 
entered are the same as for other DCB exit list routines, except that the 3 
low-order bytes of register 1 contain the address of the parameter list described in 
Figure 30 on page 98. Your abend exit routine can choose one of four options: 

• To immediately terminate your task 

• To delay the abend until all the DCBs in the same OPEN or CLOSE macro 
are opened or closed 

• To ignore the abend condition and continue processing without making 
reference to the DCB on which the abend condition was encountered, or 

• To try to recover from the error 

Not all of these options are available for each abend condition. Your DCB 
abend exit routine must determine which option is available by examining the 
contents of the option mask byte (byte 3) of the parameter list. The address of 
the parameter list is passed in register 1. Figure 30 on page 98 shows the 
contents of the parameter list and the possible settings of the option mask when 
your routine receives control. (All information in the parameter list is in binary.) 
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Bit 

Meaning 

0 

Reserved for System Use 

1-3 

Reserved for Future Use 

4 

OK to Recover 

5 

OK to Ignore 

6 

OK to Delay 

7 

Reserved for Future Use 


Fu!iword Boundary 


Displacement 

0 

System Completion Code 1 

_____-_X 

Return Code 

Option Mask 

4 

DCB Address 

8 

Open/Close/End-of-Volume Work Area Address 

12 

00 

Recovery Work Area Address 


1 1n the first 12 bits. 

Figure 30. Parameter List Passed to DCB Abend Exit Routine 


When your DCB abend exit routine returns control to the system control 
program (this can be done using the RETURN macro), the option mask byte 
should contain the setting that specifies the action you want to take. These 
actions and the corresponding settings of the option mask byte are: 

Decimal 

Value Action 

0 Abnormally terminate the task immediately. 

4 Ignore the abend condition. 

8 Delay the abend until the other DCBs being processed concurrently 

are opened or closed. 

12 Make an attempt to recover. 
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You must inspect bits 4, 5, and 6 of the option mask byte (byte 3 of the 
parameter list) to determine which options are available. If a bit is set to 1, the 
corresponding option is available. Indicate your choice by inserting the 
appropriate value in byte 3 of the parameter list, overlaying the bits you 
inspected. If you use a value that specifies an option that is not available, the 
abend is issued immediately. 

If the contents of bits 4, 5, and 6 of the option mask are 0, you must not change 
the option mask. This unchanged option mask will result in a request for an 
immediate abend. 

If bit 5 of the option mask is set to 1, you can ignore the abend by placing a 
value of 4 in byte 3 of the parameter list. Processing on the current DCB stops. 

If you subsequently attempt to use this DCB, the results are unpredictable. If 
you ignore an error in end-of-volume, control is returned to your program at the 
point that caused the end-of-volume condition (unless the end-of-volume routines 
were called by the close routines). If the end-of-volume routines were called by 
the close routines, an ABEND macro will be issued even though the ignore 
option was selected. 

If bit 6 of the option mask is set to 1, you can delay the abend by placing a value 
of 8 in byte 3 of the parameter list. All other DCBs waiting for OPEN or 
CLOSE processing will be processed before the abend is issued. For 
end-of-volume, however, you can't delay the abend because the end-of-volume 
routine never has more than one DCB to process. 

If bit 4 of the option mask is set to 1, you can attempt to recover. Place a value 
of 12 in byte 3 of the parameter list and provide information for the recovery 
attempt. Figure 31 lists the abend conditions for which recovery can be 
attempted. For abend conditions that can be ignored or delayed, see System 
Messages . 


System 

Completion 

Return 


Code 

Code 

Description of Error 

117 

X'38' 

An I/O error occurred during 
execution of a read block ID 



command issued to establish tape 
position. 


X'3C' 

DCB block count did not agree 
with the calculated block count. 


Figure 31 (Part 1 of 3). Conditions for Which Recovery Can Be Attempted 
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System 

Completion 

Code 

Return 

Code 

Description of Error 

137 

X'OC' 

DCB block count did not agree 
with the calculated block count. 


X'18' 

An I/O error occurred while 
positioning a magnetic tape data set 
to the first data record or during 
execution of a read block ID 
command issued to establish tape 
position. 


X'38' 

An I/O error occurred during 
execution of a read block ID 
command issued to establish tape 
position. 

213 

X'04' 

DSCB was not found on volume 
specified. 

214 

X'OC' 

An I/O error occurred during 
execution of a read block ID 
command issued to establish tape 
position. 


X'10' 

DCB block count did not agree 
with the calculated block count. 

237 

X'04' 

Block count in DCB does not agree 
with block count in trailer label. 

413 

X'18' 

Data set was opened for input and 
no volume serial number was 
specified. 

613 ] 

X'08' 

I/O error occurred during reading 
of tape label. 


X'OC' 

Invalid tape label was read. 


X'10' 

I/O error occurred during writing of 
tape label. 


X'14' 

I/O error occurred during writing of 
tape label. 

713 j 

X'04' 

A data set on magnetic tape was 
opened for INOUT, but the 
volume contained a data set whose 
expiration date had not been 
reached and the operator denied 
permission. 

717 

X'10' 

I/O error occurred during reading 
of trailer label 1 to update block 
count in DCB. 


Figure 31 (Part 2 of 3). Conditions for Which Recovery Can Be Attempted 
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System 

Completion 

Code 

Return 

Code 

Description of Error 

813 

X'04' 

Data set name on header label does 
not match data set name on DD 
statement. 


Figure 31 (Part 3 of 3). Conditions for Which Recovery Can Be Attempted 


Recovery Requirements 

For the recovery attempt, you should supply a recovery work area (see Figure 32 
on page 102) with a new volume serial number for each volume associated with 
an error. If no new volumes are supplied, recovery will be attempted with the 
existing volumes, but the likelihood of successful recovery is greatly reduced. 

If you request recovery for system completion code 213, return code 04, you 
must indicate in your job control language (JCL) that the volumes cannot be 
shared by specifying unit affinity, deferred mounting, or more volumes than units 
for the data set. 

If you request recovery for system completion code 237, return code 04, you 
don't need to supply new volumes or a work area. The condition that caused the 
abend is the disagreement between the block count in the DCB and that in the 
trailer label. To permit recovery, this disagreement is ignored. 

If you request recovery for system completion code 717, return code 10, you 
don't need to supply new volumes or a work area. The abend is caused by an 
I/O error during updating of the DCB block count. To permit recovery, the 
block count is not updated. Consequently, an abnormal termination with system 
completion code 237, return code 04, may result when you try to read from the 
tape after recovery. You may attempt recovery from the abend with system 
completion code 237, return code 04, as explained in the preceding paragraph. 

System completion codes and their associated return codes are described in 
System Codes. 
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Figure 32. Recovery Work Area 


The work area that you supply for the recovery attempt must begin on a 
halfword boundary and can contain the information described in Figure 32. 

Place a pointer to the work area in the last 3 bytes of the parameter list pointed 
to by register 1 and described in Figure 30 on page 98. 

If you acquire the storage for the work area by using the GETMAIN macro, you 
can request that it be freed by a FREEMAIN macro after all information has 
been extracted from it. Set the high-order bit of the option byte in the work area 
to 1 and place the number of the subpool from which the work area was 
requested in byte 3 of the recovery work area. 

Only one recovery attempt per data set is allowed during OPEN, CLOSE, or 
end-of-volume processing. If a recovery attempt is unsuccessful, you may not 
request another recovery. The second time through the exit routine you may 
request only one of the other options (if allowed): Issue the abend immediately, 
ignore the abend, or delay the abend. If at any time you select an option that is 
not allowed, the abend is issued immediately. 

Note that, if recovery is successful, you still receive an abend message on your 
listing. This message refers to the abend that would have been issued if the 
recovery had not been successful. 
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Abend Installation Exit 


The abend installation exit gives you an additional option for handling error 
situations that result in an abend. This exit is taken any time an abend condition 
occurs during the process of opening, closing, or handling an end-of-volume 
condition for a DCB. An IBIVbsupplied installation exit will give you the option 
to retry tape positioning when you receive a 613 system completion code, return 
code 08 or 0C. (For additional information about the abend installation exit, see 
System-- Data Administration and Open/Close/EOV Logic,) 


Chapter 7, DCB Exit Routines 
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Chapter 8. Spooling and Scheduling Data Sets 


The job entry subsystem (JES) is a system function that spools and schedules 
input and output data streams. 

Spooling includes two basic functions: 

• Input streams are read from the input device and stored on an intermediate 
storage device in a format convenient for later processing by the system and 
by the user's program. 

• Output streams are similarly stored on an intermediate device until a 
convenient time for printing or punching. 

Scheduling provides the highest degree of system availability through the orderly 
use of system resources that are the objects of contention. 

With spooling, unit record devices are used at full rated speed if enough buffers 
are available, and they are used only for the time needed to read, print, or punch 
the data. Without spooling, the device is occupied for the entire time that a job 
is doing other processing. Also, because data is stored instead of being 
transmitted directly, output can be queued in any order and scheduled by class 
and by priority within each class. 

You enter data into the system input stream by preceding it with a DD * or a 
DD DATA JCL statement. This is a SYSIN data set. 

Your output data can be printed or punched from a SYSOUT data set that is 
referred to as the output stream. You code the SYSOUT keyword parameter in 
your DD statement and designate the appropriate output class. For example, 
SYSOUT = A requests output class A. The class-device relationship is 
established for each installation, and a list of devices assigned to each output class 
will enable you to select the appropriate one. For further information on SYSIN 
and SYSOUT parameters, see JCL 

SYSIN and SYSOUT must be either BSAM or QSAM data sets and you open 
and close them in the same manner as any other data set processed on a unit 
record device (except when multiple DCBs are used to write to the same output 
class, the records are not interspersed.) The job entry subsystem (JES) allows 
multiple opens to SYSOUT data sets. However, serialization of the data set is 
the responsibility of the application or user. The DCB exit routine will be 
entered in the usual manner if you specify it in an exit list. 

When you use QSAM with fixed-length blocked records or BSAM, the DCB 
block size parameter does not have to be a multiple of logical record length 
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(LRECL) if the block size is specified through the SYSOUT DD statement. 
Under these conditions, if block size is greater than LRECL but not a multiple of 
LRECL, block size is reduced to the nearest lower multiple of LRECL when the 
data set is opened. This feature allows a cataloged procedure to specify blocking 
for SYSOUT data sets, even though your LRECL is not known to the system 
until execution. 

Therefore, the SYSOUT DD statement of the go step of a compile-load-go 
procedure can specify block size without block size being a multiple of LRECL. 

Because a SYSOUT data set is written on a direct access device, you should omit 
the DEVD operand in the DCB macro, or you should code DEVD = DA. 

Because SYSIN and SYSOUT data sets are spooled on intermediate devices, you 
should also avoid using device-dependent macros (such as FEOV, CNTRL, 
PRTOV, BSP, or SETPRT) in processing these data sets. (See “Device 
Independence” on page 58.) With a 3800, you can use SETPRT when 
processing spooled data sets. For further information, refer to IBM 3800 Printing 
Subsystem Programmer's Guide . 

The job entry subsystem controls all blocking and deblocking of your data to 
optimize system operation and ignores the number of channel programs (NCP) 
you specify. The block size (BLKSIZE) and number of buffers (BUFNO) 
specified in your program have no correlation with what is actually used by the 
job entry subsystem. Therefore, you can select the blocking factor that best fits 
your application program with no effect on the spooling efficiency of the system. 
For QSAM applications, move mode is as efficient as locate mode. 

All record formats are allowed, except that spanned records (RECFM = VS or 
VBS) cannot be specified for SYSIN. A record format of FIXED is supplied if it 
is not specified for SYSIN. 

The minimum record length for SYSIN is 80 bytes. For undefined records, the 
entire 80-byte image is treated as a record. Therefore, a read of less than 80 bytes 
results in the transfer of the entire 80-byte image to the record area specified in 
the READ macro. For fixed and variable length records, an abend results if the 
LRECL is less than 80 bytes. 

The logical record length value (JFCLRECL field in the JFCB) is filled in with 
the logical record length value of the input data set. This value is increased by 4 
if the record format is variable (RECFM = V or VB). The logical record length 
may be a size other than the size of the input device, if the SYSIN input stream 
is supplied by an internal reader. The job entry subsystem will supply a value in 
the JFCLRECL field of the JFCB if that field is found to be zero. 

The block size value (JFCBLKSI field in the JFCB) is filled in with the block 
size value of the input data set. This value is increased by 4 greater than the 
value calculated for the logical record value (that is, input data set logical record 
length + 4) if the record format is variable (RECFM = V or VB). The job entry 
subsystem will supply a value in the JFCBLKSI field of the JFCB if that field is 
found to be 0. 
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Your program is responsible for printing format, pagination, header control, and 
stacker select. You can supply control characters for SYSOUT data sets in the 
normal manner by specifying ANSI or machine characters in the DCB. Standard 
controls are provided by default if they are not specified. The length of output 
records must not exceed the allowable maximum length for the ultimate device. 
Cards can be punched in EBCDIC mode only. 

Your SYNAD routine will be entered if an error occurs during data transmission 
to or from an intermediate storage device. Again, because the specific device is 
indeterminate, your SYNAD routine code should be device independent. 
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Chapter 9. Processing a Sequential Data Set 


Data sets residing on any volume other than direct access volumes must be 
processed sequentially. In addition, a data set residing on a direct access volume, 
regardless of organization, can be processed sequentially. This includes data sets 
created using ISAM or a similar access method. Because the entire data set 
(prime, index, and overflow areas) will be processed, care should be taken to 
determine, the type of records being processed. 

Either the queued or the basic access technique may be used to store and retrieve 
the records of a sequential data seit. For a non-DASD sequential data set, a 
technique called chained scheduling can be used to accelerate the input/output 
operations. 


Creating a Sequential Data Set 

As discussed earlier, a processing program should be developed using, as much as 
possible, factors that are constant, with variable factors specified at execution. 

For that reason, the following examples are generalized as much as possible. 

They are neither exhaustive nor intended as complete examples. Rather, they are 
presented as introductory sequences. 

In creating a sequential data set on a magnetic tape or direct access device, you 
must do the following: 

• Code DSORG= PS or PSU in the DCB macro. 

• Code a DD statement to describe the data set (see JCL). 

• Process the data set with an OPEN macro (data set is opened for output or 
OUTIN), a series of PUT or WRITE and CHECK macros, and then a 
CLOSE macro. 

Tape-to-Print, Move Mode—Simple Buffering: The example in Figure 33 on 
page 110 shows that the GET-move and PUT-move require two movements of 
the data records. If the record length (LRECL) does not change during 
processing, only one move is necessary; you can process the record in the input 
buffer segment. A GET-locate can be used to provide a pointer to the current 
segment. 
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OPEN 

(INDATA,,OUTDATA,(OUTPUT)) 


NEXTREC 

GET 

INDATA,WORKAREA 

Move mode 


AP 

NUMBER,=P' 1' 



UNPK 

COUNT,NUMBER 

Record count adds 6 


PUT 

OUTDATA,COUNT 

bytes to each record 


B 

NEXTREC 


TAPERROR 

SYNADAF 

ACSMETH=QSAM 

Control program returns 


LA 

0,68(0,1) 

message address in regis¬ 

* 



ter 1. 


ST 

14,SAVE14 

SYNAD routine prints part 


PUT 

OUTDATA,(0) 

of the message (beginning 


SYNADRLS 


with the unit number) as 


L 

14,SAVE14 

a 56-byte fixed-length 


RETURN 


record. It then returns 

ENDJOB 

CLOSE 

(INDATA,,OUTDATA) 

to the control program. 

COUNT 

DS’ 

CL6 


WORKAREA 

DS 

CL50 


NUMBER 

DC 

PL4'0' 


SAVE14 

DS 

F 


INDATA 

DCB 

DDNAME=INPUTDD,DS0RG=PS,MACRF=(GM),ER0PT=ACC, C 


SYNAD=TAPERROR,E0DAD=ENDJOB 


OUTDATA 

DCB 

DDNAME=OUTPUTDD,DS0RG=PS,MACRF=(PM),ER0PT=ACC 


| Figure 33. Creating a Sequential Data Set—Move Mode, Simple Buffering 

4 


Retrieving a Sequential Data Set 

In retrieving a sequential data set on a magnetic tape or a direct access device, 
you must do the following: 

• Code DSORG= PS or PSU in the DCB macro. 

• Tell the system where your data set is located (by coding a DD statement; see 
JCL). 

• Process the data set with an OPEN macro (data set is opened for input, 
INOUT, RDBACK, or UPDAT), a series of GET or READ macros, and 
then a CLOSE macro. 

Tape-to-Print, Locate Mode—Simple Buffering: The example in Figure 34 on 
page 111 is similar to that in Figure 33. However, because there is no change in 
the record length, the records can be processed in the input buffer. Only one 
move of each data record is required. 
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OPEN 

(INDATA,,OUTDATA, 

(OUTPUT),ERRORDCB,(OUTPUT)) 

NEXTREC 

GET 

INDATA 

Locate mode 


LR 

2,1 

Save pointer 


AP 

NUMBER,=P'1' 



UNPK 

0(6,2),NUMBER 

Process in input area 


PUT 

OUTDATA 

Locate mode 


MVC 

0(50,1),0(2) 

Move record to output buffer 


B 

NEXTREC 

TAPERROR 

SYNADAF 

ACSMETH=QSAM 

Message address in register 1 


ST 

2,SAVE2 

Save register 2 contents 


L 

2,8(0,1) 

Load pointer to input buffer 


MVC 

8(70,1) 50(1) 
78(1),C f ' 

Shift nonblank message fields 


MV I 

Blank end of message 


MVC 

79(49,1),78(1) 


ST 

2,128(1) 

0,=H 4 

Save address for debugging 


CH 

Test SYNADAF return code 


BE 

MOVERCD 

Branch if data read 


BL 

PRINTIT 

Branch if data not read 


CLI 

128(1),C' ' 

See if data read anyway 


BE 

PRINTIT 

Branch if definitely no data 

MOVERCD 

MVC 

78(50,1),0(2) 

Add input record to message 

PRINTIT 

LA 

0,4(1) 

Load address of message 


LR 

2,14 

Save return address 


PUT 

ERRORDCB,(0) 

Print message (move mode) 


SYNADRLS 


Release message and save area 


LR 

14,2 

Restore return address 


L 

2, SAVE2 

Restore register 2 contents 


RETURN 


Return to control program 

ENDJOB 

CLOSE 

(INDATA,,OUTDATA, 

,ERRORDCB) 

NUMBER 

DC* 

PL4 1 0' 


INDATA 

DCB 

DDNAME=INPUTDD,DSORG=PS,MACRF=(GL),EROPT=ACC, 


SYNAD=TAPERROR,EODAD=ENDJOB 

OUTDATA 

DCB 

DDNAME--OUTPUTDD, DSORG=PS, MACRF=(PL) 

ERRORDCB 

DCB 

DDNAME=SYSOUTDD,DSORG=PS,MACRF=(PM),RECFM=V, 


BLKSIZE=128,LRECL=124 


SAVE 2 

DS 

F 



Figure 34, Creating a Sequential Data Set—Locate Mode, Simple Buffering 
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Modifying a Sequential Data Set 


You can modify a sequential data set in two ways: 

• Changing the data in existing records (update in place) 

• Adding new records to the end of a data set (extending the data set) 

Updating a Sequential Data Set in Place 

When you update in place, you read records, process them, and write them back 
to their original positions without destroying the remaining records on the track. 
The following rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro 
instruction. To perform the update, you can use only the READ, WRITE, 
CHECK, NOTE, POINT, GET, and PUTX macros. 

• You cannot delete any record or change its length; you cannot add new 
records. 

• The data set must be on a direct access device. 

A record must be retrieved by a READ or GET macro before it can be updated 
by a WRITE or PUTX macro. A WRITE or PUTX macro does not need to be 
issued after each READ or GET macro. The READ and WRITE macros must 
be execute forms that refer to the same DECB; the DECB must be provided by 
the list forms of the READ or WRITE macros. (The execute and list forms of 
the READ and WRITE macros are described in Data Administration: Macro 
Instruction Reference .) 

Updating with Overlapped Operations 

To overlap input/output and processor activity, you can start several read or 
write operations before checking the first for completion. You cannot overlap 
read with write operations, however, as operations of one type must be checked 
for completion before operations of the other type are started or resumed. Note 
that each pending read or write operation requires a separate channel program 
and a separate DECB. If a single DECB were used for successive read 
operations, only the last record read could be updated. 

In Figure 52 on page 145, overlap is achieved by having a read or write request 
outstanding while each record is being processed. Note the use of the execute 
and list forms of the READ and WRITE macros, identified by the operands 
MF ” E and ME = L. 
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Extending a Sequential Data Set 


If you want to add records at the end of your data set, you must open the data 
set for output with DISP= MOD specified in the DD statement or specify the 
EXTEND option of the OPEN macro. You can then issue PUT or WRITE 
macros to the data set. 

Concatenating Sequential Data Sets 

Concatenation is a method by which a collection of sequential data sets can be 
treated by the application program as one data set. For example, two or more 
sequential data sets can be automatically retrieved by the system and processed 
successively as a single data set. It is important to consider the characteristics of 
the individual data sets being concatenated. Data sets with like characteristics are 
those that may be processed correctly using the same data control block (DCB), 
input/output block (IOB), and channel program. Any variation (such as record 
format, device, or option) makes them unlike. 

Differing block sizes make data sets unlike unless the first block size in the 
concatenation is greater than any block size following. However, the system will 
automatically adjust buffers and channel programs for eligible data sets, if 
necessary. The primary purpose of this service is to permit otherwise 
homogeneous data sets to be concatenated in any order. Eligibility rules are: 

• Data set resides on DASD 

• RECFM cannot be U (RECFM can be F or V) 

• Records are blocked 

• LRECL is same for all data sets being concatenated 

• Access method is QSAM 

• OPEN got the buffer pool 

• Block size was not coded in the DCB macro 

Note: Block size can be coded in DD statements, via TSO ALLOCATE 
commands, or in the data set label. 

When sequential data sets are concatenated, the system is open to only one of the 
data sets at a time. You must inform the system by modifying the DCBOFLGS 
field of the DCB if unlike sequential data sets are concatenated (this is not 
required for spool data sets, because EOV automatically treats them as unlike 
data sets). The indication must be made before the end of the current data set is 
reached. You must set bit 4 to 1 by using the instruction OI DCBOFLGS, X'08' 
as described in Chapter 5, “Specifying a Data Control Block and Initializing 
Data Sets.” If bit 4 of the DCBOFLGS field is 1, end-of-volume processing for 
each data set will issue a close for the data set just read and an open for the next 
concatenated data set. This opening and closing procedure updates the fields in 
the DCB and, if necessary, builds a new IOB and a new channel program. If the 
buffer pool was obtained automatically by the open routine, the procedure also 
frees the buffer pool and obtains a new one for the next concatenated data set. 
The procedure does not issue a freepool for the last concatenated data set. 

Unless you have some way of determining the characteristics of the next data set 
before it is opened, you should not reset the DCBOFLGS field to indicate like 
attributes during processing. When you concatenate data sets with unlike 
attributes, no EOV exits are taken. 
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When unlike sequential data sets are concatenated, the GET or READ macro 
instruction that detected the end of data set 5 must be reissued. Figure 35 on 
page 114 illustrates a possible routine for determining when a GET or READ 
must be reissued. Also, you should not issue multiple input requests (that is, a 
series of READ or GET macros instructions) in your program. If you do, you 
will have to arrange some way to determine which requests have been completed 
and which must be reissued. These restrictions do not apply to like data sets, 
because no OPEN or CLOSE operation is necessary between data sets. 




*Returns are to control 
program address in register 14 


Figure 35. Reissuing a READ or GET for Unlike Concatenated Data Sets 


When the change from one data set to another is made, label exits are taken as 
required; automatic volume switching is also performed for multiple volume data 
sets. Your end-of-data-set (EODAD) routine is not entered until the last data set 
has been processed. 

To save time when processing two consecutive sequential data sets on a single 
tape volume, you specify LEAVE in your OPEN macro instruction. 
Concatenated data sets cannot be read backward. 
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Processing with Chained Scheduling 


To accelerate the input/output operations required for a data set, the operating 
system provides a technique called chained scheduling. When requested, the 
system bypasses the normal I/O routines and dynamically chains several 
input/output operations together. A series of separate read or write operations, 
functioning with chained scheduling, is issued to the computing system as one 
continuous operation. In a nonpageable (V = R) address space, the 
program-controlled interruption (PCI) flag in the CCWs cause the PCI 
appendage to get control and dynamically chain the next I/O request to the 
currently executing channel program. 

The I/O performance is improved by reduction in both the processor time and 
the channel start/stop time required to transfer data within virtual storage. Some 
factors that affect performance improvement are: 

• Address space type (real or virtual) 

• BUFNO for QSAM 

• The number of overlapped requests for BSAM (NCP) 

• Other activity on the processor and channel 

Chained scheduling can be used only with simple buffering. Each data set for 
which chained scheduling is specified must be assigned at least two and preferably 
more buffers with QSAM, or must have a value of at least two and preferably 
more for NCP with BSAM or BPAM. 

The system will default to chained scheduling for nondirect access devices (other 
than printers and format-U records on nondirect access devices), except for those 
cases in which it is not allowed. 

A request for exchange buffering in MVS/XA is not honored, but compatibly 
defaults to move mode and therefore has no effect on either a request for chained 
scheduling or a default to chained scheduling. 

A request for chained scheduling will be ignored and normal scheduling used if 
any of the following are encountered when the data set is opened: 

• CNTRL macro to be used. 

• Bypassing of embedded DOS checkpoint records on tape input. 

• Spooled data sets (SYSIN or SYSOUT). 

• NCP= 1 or BUFNO =1 

• A print data set or any associated data set for the 3525 Card Punch. (For 
more information about programming the 3525, see OS and OS I VS 
Programming Support for the IBM 3505 Card Reader and IBM 3525 Card 
Punch.) 
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The number of channel program segments that can be chained is limited to the 
value specified in the NCP operand of BSAM DCBs, and to the value specified 
in the BUFNO operand of QSAM DCBs. 

When the data set is a printer, chained scheduling is not supported 

(DCB = OPTCD = C) when channel 9 or channel 12 is in the carriage control 

tape or FCB. 

When chained scheduling is being used, the automatic skip feature of the 
PRTOV macro for the printer will not function. Format control must be 
achieved by ANSI or machine control characters. (Control characters are 
discussed in more detail under “Carriage Control Character” on page 31, under 
“Record Format—Device Type Considerations” on page 28, and under 
Appendix B, “Control Characters” on page 213.) When you are using QSAM 
under chained scheduling to read variable-length, blocked, ASCII tape records 
(format-DB), you must code BUFOFF = L in the DCB for that data set. 

Note also that, if you are using BSAM with the chained scheduling option to 
read format-DB records and have coded a value for the BUFOFF operand other 
than BUFOFF = L, the input buffers will be converted from ASCII to EBCDIC 
as usual, but the record length returned to the DCBLRECL field will equal the 
block size, not the actual length of the record read in; the record descriptor word 
(RDW), if present, will not have been converted from ASCII to binary. 

Chained scheduling is most valuable for programs that require extensive input 
and output operations. Because a data set using chained scheduling may 
monopolize available time on a channel in a V = R region, separate channels 
should be assigned, if possible, when more than one data set is to be processed. 

Note: Chained scheduling is not a DASD option; it is built into the access 
method for DASD. 

Chained Scheduling Functions for DASD 

For direct access storage devices (DASD), chained scheduling is not supported. 
(If the chained scheduling option is specified for DASD, it is ignored.) Instead, 
the functions of chained scheduling are performed directly by the sequential 
access method (either BSAM or QSAM). 

In QSAM, the value of BUFNO determines how many channel programs or I/O 
requests will be chained together before I/O is initiated. The default value of 
BUFNO is 5; when five buffers are full (that is, five I/O requests have been 
issued), QSAM reads or writes all five records in a single revolution of the disk. 

In BSAM, the first READ or WRITE instruction initiates I/O. Subsequent I/O 
requests (without an associated CHECK or WAIT instruction) will be put in a 
queue, and the channel program associated with the request will be chained to 
the previous request in the queue. During channel end processing for the first 
I/O request, the queue is checked for pending I/O requests and the next request 
in the queue is started using the channel end appendage. The number of I/O 
requests that may be chained together is limited to the number of requests that 
can be handled in one I/O event (and one revolution of the disk) before channel 
end processing is complete. 
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Search Direct for Input Operations 


To accelerate the input operations required for a data set on DASD, the 
operating system uses a technique called search direct. Search direct reads in the 
requested record and the count field of the next record. This allows the operation 
to get the next record directly, along with the count field of the following record. 

You may receive unpredictable results when your application has a dependency 
that is incompatible with the use of search direct. For example, you may receive 
unpredictable results when multiple DCBs are open for a file and one of the 
applications is adding records. 


Determining the Length of a Record on Input 

When you read a sequential data set, you can determine the length of the record 
in one of the following five ways, depending upon the record format of the data 
set: 

1. For fixed-length, unblocked records, the length of all records is the value in 
the DCBBLKSI field of the DCB. 

2. For variable-length records, the block descriptor word in the record contains 
the length of the record. 

3. For fixed-length blocked or undefined-length records, the following method 
can be used to calculate the block length. This method can be used with 
BSAM, BDAM, or BPAM. (This method should not be used when reading 
track overflow records or when using chained scheduling with format-U 
records. In these cases, the length of a record cannot be determined.) After 
checking the DECB for the READ request but before issuing any subsequent 
data management macros that specify the DCB for the READ request, 
obtain the IOB address from the DECB. The IOB address can be loaded 
from the location 16 bytes from the start of the DECB. 

Obtain the residual count from the channel status word (CSW) that has been 
stored in the input/output block (IOB). The residual count is in the 
halfword, 14 bytes from the start of the IOB. For SYSIN or SYSOUT data 
sets, the residual count can also be found in bytes 2 and 3 of the first word of 
the DECB. Subtract this residual count from the number of data bytes 
requested to be read by the READ macro instruction. If 1 S f was coded as 
the length parameter of the READ macro, the number of bytes requested is 
the value of DCBBLKSI at the time the READ was issued. If the length 
was coded in the READ macro, this value is the number of data bytes and it 
is contained in the halfword 6 bytes from the beginning of the DECB. The 
result of the subtraction is the length of the block read. See Figure 36 on 
page 118. 
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OPEN 

(DCB,(INPUT)) 


LA 

DCBR,DCB 


USING 

IHADCB,DCBR 


READ 

DECB1,SF,DCB,AREA1,'S' 


READ 

DECB2,SF,DCB,AREA2,50 


CHECK 

DECB1 


LH 

W0RK1,DCBBLKSI 

Block size at time of READ 

L 

W0RK2,DECB1+16 

I0B address 

SH 

W0RK1,14(W0RK2) 

W0RK1 has block length 

CHECK 

DECB 2 


LH 

W0RK1,DECB2+6 

Length requested 

L 

W0RK2,DECB2+16 

I0B address 

SH 

W0RK1,14(W0RK2) 

W0RK1 has block length 

MVC 

DCBBLKSI,LENGTH3 

Length to be read 

READ 

DECB3,SF,DCB,AREA3 

CHECK 

DECB3 


LH 

W0RK1,LENGTH3 

Block size at time of READ 

L 

W0RK2,DECB+16 

I0B address 

SH 

WORK1,14(W0RK2) 

W0RK1 has block length 

DCB 

DCBD 

...RECFM=U,NCP=2,... 



Figure 36. One Method of Determining the Length of the Record When Using BSAM to Read Undefined-Length 
Records 


4. When an undefined-length record is read, the actual length of the record is 
returned in the DCBLRECL field of the data control block. Because of this 
use of DCBLRECL, the LRECL operand should be omitted. This method 
can only be used with QSAM and BSAM. 

5. The length to be read or written can be supplied dynamically in a 
READ/WRITE macro using BSAM. This method cannot be used when 
using chained scheduling on any nondirect access device. 


118_ MVS/XA Data Administration Guide 





Writing a Short Block When Using the BSAM WRITE Macro 

If you have fixed-blocked record format, you can change the length of a block 
when you are writing blocks for a sequential data set. The DCB block size field 
(DCBBLKSI) can be changed to specify a block size that is shorter than what 
was originally specified for the data set. The DCBBLKSI field must be changed 
before issuing the WRITE macro instruction and must be a multiple of the 
LRECL parameter in the DCB. Any subsequent WRITE macros issued will 
write records with the new block length until the block size is changed again. 
The DCB block size field should not be changed to specify a block size that is 
greater than what was originally specified for the data set. 


< 


Managing SAM Buffer Space 

The operating system provides several methods of buffer acquisition and control. 
Each buffer (virtual storage area used for intermediate storage of input/output 
data) usually corresponds in length to the size of a block in the data set being 
processed. When you use the queued access technique, any reference to a buffer 
actually refers to the next record (buffer segment). 

You can assign more than one buffer to a data set by associating the buffer with 
a buffer pool. A buffer pool must be constructed in a virtual storage area 
allocated for a given number of buffers of a given length. 

The number of buffers you assign to a data set should be a trade-off against the 
frequency with which you refer to each buffer. A buffer that is not referred to for 
a relatively long period of time may be paged out. If this were allowed to happen 
to any considerable degree, it could decrease throughput. 

Buffer segments and buffers within the buffer pool are controlled automatically 
by the system when the queued access technique is used. However, you can tell 
the system you are finished processing the data in a buffer by issuing a release 
(RELSE) macro for input or a truncate (TRUNC) macro instruction for output. 
The simple buffering technique can be used to process a sequential data set or an 
indexed sequential data set. 

If you use the basic access technique, you can use buffers as work areas rather 
than as intermediate storage areas. You can control them directly, by using the 
GETBUF and FREEBUF macros, or dynamically for BDAM and BISAM, by 
requesting dynamic buffering in your DCB macro instruction and your READ or 
WRITE macro. If you request dynamic buffering, the system will automatically 
provide a buffer each time a READ macro is issued. That buffer will be freed 
when you issue a WRITE or FREEDBUF macro instruction. 
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Buffer Pool Construction 


Buffer pool construction can be accomplished in any of three ways: 

♦ Statically, using the BUILD macro 

♦ Explicitly, using the GETPOOL macro 

♦ Automatically, by the system, when the data set is opened 

If QSAM simple buffering is used, the buffers are automatically returned to the 
pool when the data set is closed. If the buffer pool is constructed explicitly or 
automatically, the virtual storage area must be returned to the system by the 
FREEPOOL macro. 

In many applications, fullword or doubleword alignment of a block within a 
buffer is important. You can specify in the DCB that buffers are to start on 
either a doubleword boundary or a fullword boundary that is not also a 
doubleword boundary (by coding BFALN = D or F). If doubleword alignment is 
specified for format-V records, the fifth byte of the first record in the block is so 
aligned. For that reason, fullword alignment must be requested to align the first 
byte of the variable-length record on a doubleword boundary. The alignment of 
the records following the first in the block depends on the length of the previous 
records. 

Note that buffer alignment provides alignment only for the buffer. If records 
from ISCII/ASCII magnetic tape are read and the records use the block prefix, 
the boundary alignment of logical records within the buffer depends on the length 
of the block prefix. If the length is 4, logical records are on fullword boundaries. 
If the length is 8, logical records are on doubleword boundaries. 

If the BUILD macro is used to construct the buffer pool, alignment depends on 
the alignment of the first byte of the reserved storage area. 

When you process multiple QISAM data sets, you can use a common buffer 
pool. To do this, however, you must use the BUILD macro instruction to 
reformat the buffer pool before opening each data set. 

BUILD—Construct a Buffer Pool 

When you know, before program assembly, both the number and the size of the 
buffers required for a given data set, you can reserve an area of appropriate size to 
be used as a buffer pool. Any type of area can be used—for example, a 
predefined storage area or an area of coding no longer needed. 

A BUILD macro, issued during execution of your program, structures the 
reserved storage area into a buffer pool. The address of the buffer pool must be 
the same as that specified for the buffer pool control block (BUFCB) in your 
DCB. The buffer pool control block is an 8-byte field preceding the buffers in 
the buffer pool. The number (BUFNO) and length (BUFL) of the buffers must 
also be specified. The length of BUFL must be at least the block size. 
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When the data set using the buffer pool is closed, you can reuse the area as 
required. You can also reissue the BUILD macro to reconstruct the area into a 
new buffer pool to be used by another data set. 

You can assign the buffer pool to two or more data sets that require buffers of 
the same length. To do this, you must construct an area large enough to 
accommodate the total number of buffers required at any one time during 
execution. That is, if each of two data sets requires 5 buffers (BUFNO = 5), the 
BUILD macro should specify 10 buffers. The area must also be large enough to 
contain the 8-byte buffer pool control block. 

BUILDRCD—Build a Buffer Pool and a Record Area 

The BUILDRCD macro, like the BUILD macro, causes a buffer pool to be 
constructed in an area of virtual storage you provide. In addition, BUILDRCD 
makes it possible for you to access variable-length, spanned records as complete 
logical records, rather than as segments. 

You must be processing with QSAM in the locate mode and you must be 
processing either VS/VBS or DS/DBS records, if you want to access the 
variable-length, spanned records as logical records. If you issue the BUILDRCD 
macro before the data set is opened, or during your DCB exit routine, you 
automatically get logical records rather than segments of spanned records. 

Only one logical record storage area is built, no matter how many buffers are 
specified; therefore, you can't share the buffer pool with other data sets that may 
be open at the same time. 

GETPOOL-Get a Buffer Pool 

If a specified area is not reserved for use as a buffer pool, or if you want to defer 
specifying the number and length of the buffers until execution of your program, 
you should use the GETPOOL macro instruction. It enables you to vary the 
size and number of buffers according to the needs of the data set being processed. 

The GETPOOL macro causes the system to allocate a virtual storage area to a 
buffer pool. The system builds a buffer pool control block and stores its address 
in the data set's DCB. The GETPOOL macro should be issued either before 
opening of the data set or during your DCB's OPEN exit routine. 

When using GETPOOL with QSAM, specify a buffer length (BUFL) at least as 
large as the block size. 

Automatic Buffer Pool Construction 

If you have requested a buffer pool and have not used an appropriate macro by 
the end of your DCB exit routine, the system automatically allocates virtual 
storage space for a buffer pool. The buffer pool control block is also assigned 
and the pool is associated with a specific DCB. For BSAM, a buffer pool is 
requested by specifying BUFNO. For QSAM, BUFNO can be specified or 
allowed to default to 5. If you are using the basic access technique to process an 
indexed sequential or direct data set, you must indicate dynamic buffer control. 
Otherwise, the system does not construct the buffer pool automatically. 
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Because a buffer pool obtained automatically is not freed automatically when you 
issue a CLOSE macro, you should also issue a FREEPOOL or FREEMAIN 
macro (discussed in the next section). 

FREEPOOL—Free a Buffer Pool 

Any buffer pool assigned to a DCB either automatically by the OPEN macro 
(except when dynamic buffer control is used) or explicitly by the GETPOOL 
macro should be released before your program is terminated. The FREEPOOL 
macro should be issued to release the virtual storage area as soon as the buffers 
are no longer needed. When you are using the queued access technique, you 
must close the data set first. If you are not using the queued access technique, it 
is still advisable to close the data set first. 

If the OPEN macro was issued while running under a protect key of zero, a 
buffer pool that was obtained by OPEN should be released by issuing the 
FREEMAIN macro instead of the FREEPOOL macro. This is necessary 
because the buffer pool acquired under these conditions will be in storage 
assigned to subpool 252. 


Constructing a Buffer Pool 


Figure 37 and Figure 38 on page 123 illustrate several possible methods of 
constructing a buffer pool. They do not consider the method of processing or 
controlling the buffers in the pool. 

In Figure 37, a static storage area named INPOOL is allocated during program 
assembly. The BUILD macro, issued during execution, arranges the buffer pool 
into 10 buffers, each 52 bytes long. Five buffers are assigned to INDCB and 5 to 
OUTDCB, as specified in the DCB macro for each. The two data sets share the 
buffer pool because both specify INPOOL as the buffer pool control block. 
Notice that an additional 8 bytes have been allocated for the buffer pool to 
contain the buffer pool control block. The 4-byte chain pointer that occupies the 
first 4 bytes of the buffer is included in the buffer, so no allowance need be made 
for this field. 
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Figure 37. Constructing a Buffer Pool from a Static Storage Area 


In Figure 38 on page 123, two buffer pools are constructed explicitly by the 
GETPOOL macros. Ten input buffers are provided, each 52 bytes long, to 
contain one fixed-length record; 5 output buffers are provided, each 112 bytes 


122 MVS/XA Data Administration Guide 


long, to contain 2 blocked records plus an 8-byte count field (required by ISAM). 
Notice that both data sets are closed before the buffer pools are released by the 
FREEPOOL macros. The same procedure should be used if the buffer pools 
were constructed automatically by the OPEN macro. 
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Buffer Control 


Your program can use any of four techniques to control the buffers used by your 
program. The advantages of each depend to a great extent upon the type of job 
you are doing. Simple buffering is provided for the queued access technique. 

The basic access technique provides for either direct or dynamic buffer control. 

Although only simple buffering can be used to process an indexed sequential data 
set, buffer segments and buffers within a buffer pool are controlled automatically 
by the operating system. 

In addition, the queued access technique provides three processing modes that 
determine the extent of data movement in virtual storage. Move, data, and locate 
mode processing can be specified for either the GET or PUT macro. (Substitute 
mode is no longer supported; the system defaults to move mode.) The 
movement of a record is determined as follows: 

• Move mode— The record is moved from a system input buffer to your work 
area, or from your work area to an output buffer. 

• Data mode (QSAM format-V spanned records only)— The same as the move 
mode, except that only the data portion of the record is moved. 

• Locate mode— The record is not moved. Instead, the address of the next 
input or output buffer is placed in register 1. For QSAM format-V spanned 
records, if you have specified logical records by specifying BFTEK = A or by 
issuing the BUILDRCD macro, the address returned in register 1 points to a 
record area where the spanned record is assembled or segmented. 

The PUT-locate routine uses the value in the DCBLRECL field to determine 
whether another record will fit into your buffer. Therefore, when you write a 
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short record, you can maximize the number of records per block by 
modifying the DCBLRECL field before you issue a PUT-locate to get a 
buffer segment for the short record. The processing sequence follows: 

1. Register 1 is returned to you with the address of the next buffer segment. 

2. Move the record into the output buffer segment. 

3. Put the length of the next (short) record into DCBLRECL. 

4. Issue PUT-locate. 

5. Move the short record into the buffer segment. 

• Substitute mode— Move mode is used when substitute mode is requested in 
MVS/XA. 

Two processing modes of the PUTX macro can be used in conjunction with a 
GET-locate macro. The update mode returns an updated record to the data set 
from which it was read; the output mode transfers an updated record to an 
output data set. There is no actual movement of data in virtual storage. The 
processing mode is specified by the operand of the PUTX macro, as explained in 
Data Administration: Macro Instruction Reference. 

If you use the basic access technique, you can control buffers in one of two ways: 

• Directly, using the GETBUF macro to retrieve a buffer constructed as 
described above. A buffer can then be returned to the pool by the 
FREEBUF macro. 

• Dynamically, by requesting a dynamic buffer in your READ or WRITE 
macro. This technique can be used only when you are using BIS AM or 
BDAM. If you request dynamic buffering, the system automatically provides 
a buffer each time a READ macro is issued. The buffer is supplied from a 
buffer pool that is created by the system when the data set is opened. The 
buffer is released (returned to the pool) upon completion of a WRITE macro 
instruction when you are updating. If you do not update the record in the 
buffer and thus release the buffer without writing the record, the 
FREEDBUF macro may be used. If you are processing an indexed 
sequential data set, the buffer is automatically released upon the next issuance 
of the READ macro instruction if there has been no intervening WRITE or 
FREEDBUF macro. 


Simple Buffering 


The term simple buffering refers to the relationship of segments within the buffer. 
All segments in a simple buffer are together in storage and are always associated 
with the same data set. When the buffer pool is constructed, the system creates a 
channel command word (CCW) for each buffer in the buffer pool. For this 
reason, each record must be physically moved from an input buffer segment to an 
output buffer segment. It can be processed within either segment or in a work 
area. 
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If you use simple buffering, records of any format can be processed. New records 
can be inserted and old records deleted as required to create a new data set. A 
record can be moved and processed as follows: 

• Processed in an input buffer and then moved to an output buffer 
(GET-locate, PUT-move/ P UTX-output) 

• Moved from an input buffer to an output buffer where it can be processed 
(GET-move, PUT-locate) 

• Moved from an input buffer to a work area where it can be processed and 
then moved to an output buffer (GET-move, PUT-move) 

• Processed in an input buffer and returned to the same data set (GET-locate, 
PUTX-update) 

The following examples illustrate the control of simple buffers and the processing 
modes that can be used. The buffer pools may have been constructed in any way 
previously described. 

Simple Buffering—GET-locate, PUT-move/PUTX-output: The GET macro (step 
A, Figure 39 on page 126) locates the next input record to be processed. Its 
address is returned in register 1 by the system. The address is passed to the PUT 
macro in register 0. 

The PUT macro (step B, Figure 39) specifies the address of the record in register 
0. The system then moves the record to the next output buffer. 

Note: The PUTX-output macro can be used in place of the PUT-move macro. 
However, processing will be as described under “Exchange Buffering” (see 
PUT-substitute). 

Simple Buffering—GET-move, PUT-locate: The PUT macro locates the address 
of the next available output buffer. Its address is returned in register 1 and is 
passed to the GET macro in register 0. 

The GET macro specifies the address of the output buffer into which the system 
moves the next input record. 

A filled output buffer is not written until the next PUT macro instruction is 
issued. 

Simple Buffering—GET-move, PUT-move: The GET macro (step A, Figure 40 
on page 126) specifies the address of a work area into which the system moves 
the next record from the input buffer. 
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GET 



Figure 39. Simple Buffering with MACRF = GL and MACRF = PM 



Figure 40. Simple Buffering with MACRF = GM and MACRF = PM 


The PUT macro (step B, Figure 40) specifies the address of a work area from 
which the system moves the record into the next output buffer. 
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Simple Buffering—GET-locate, PUT-locate: The GET macro (step A, 

Figure 41) locates the address of the next available input buffer. The address is 
returned in register 1. 


GET 
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Figure 41. Simple Buffering with MACRF = GL and MACRF = PL 


The PUT macro (step B, Figure 41) locates the address of the next available 
output buffer. Its address is returned in register 1. You must then move the 
record from the input buffer to the output buffer (step C, Figure 41). Processing 
can be done either before or after the move operation. 

A filled output buffer is not written until the next PUT macro instruction is 
issued. The CLOSE and FEOV macros write the last record of your data set by 
issuing TRUNC and PUT macro instructions. Be careful not to issue an extra 
PUT before issuing CLOSE or FEOV Otherwise, when the CLOSE or FEOV 
macro tries to write your last record, the extra PUT will write a meaningless 
record or produce a sequence error. 

Simple Buffering— UPDA T Mode: When a data set is opened with UPDAT 
specified (Figure 42 on page 128), only GET-locate and PUTX-update are 
supported. The GET macro locates the next input record to be processed and its 
address is returned in register 1 by the system. The user may update the record 
and issue a PUTX macro that will cause the block to be written back in its 
original location in the data set after all the logical records in that block have 
been processed. 
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(No movement of data takes place) 

Figure 42. Simple Buffering with MACRF=GL and MACRF = PM-UPDAT Mode 


Exchange Buffering 


Exchange buffering is not supported in MVS/XA. Its request is ignored by the 
system and move mode is used instead. 


Buffering Techniques and GET/PUT Processing Modes 

As you can see from the previous examples, the most efficient code is achieved by 
use of automatic buffer pool construction, and GET-locate and PUTX-output 
with simple buffering. Figure 43 summarizes the combinations of buffering 
techniques and processing modes that can be used. 
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Figure 43. Buffering Technique and GET/PUT Processing Modes 
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RELSE—Release an Input Buffer 


When using the queued access technique to process a sequential or an indexed 
sequential data set, you can direct the system to ignore the remaining records in 
the input buffer being processed. The next GET macro retrieves a record from 
another buffer. If format-V spanned records are being used, the next logical 
record obtained may begin on any segment in any subsequent block. 

If you are using move mode, the buffer is made available for refilling as soon as 
the RELSE macro is issued. When you are using locate mode, the system does 
not refill the buffer until the next GET macro is issued. If a PIJTX macro has 
been used, the block is written before the buffer is refilled. 

TRUNC—Truncate an Output Buffer 

When using the queued access technique to process a sequential data set, you can 
direct the system to write a short block. The first record in the next buffer is the 
next record processed by a PUT-output or PUTX-output mode. 

If the locate mode is being used, the system assumes that a record has been 
placed in the buffer segment pointed to by the last PUT macro. 

The last block of a data set is truncated by the close routine. Note that a data set 
containing format-F records with truncated blocks cannot be read from direct 
access storage as efficiently as a standard format-F data set. 

GETBUF— Get a Buffer from a Pool 

The GETBUF macro can be used with the basic access technique to request a 
buffer from a buffer pool constructed by the BUILD, GETPOOL, or OPEN 
macro. The address of the buffer is returned by the system in a register you 
specify when you issue the macro. If no buffer is available, the register contains a 
0 instead of an address. 

FREEBUF—Return a Buffer to a Pool 

The FREEBUF macro is used with the basic access technique to return a buffer 
to the buffer pool from which it was obtained by a GETBUF macro. Although 
the buffers need not be returned in the order in which they were obtained, they 
must be returned when they are no longer needed. 

FREEDBUF—Return a Dynamic Buffer to a Pool 

Any buffer obtained through the dynamic buffer option must be released before it 
can be used again. When you are processing a direct data set, if you do not 
update the block in the buffer and thus need to free the buffer instead of writing 
the block, you must use the FREEDBUF macro. If there is an uncorrectable 
input/output error, the control program releases the buffer. When you are 
processing an indexed sequential data set, if you do not update the block in the 
buffer or, if there is an uncorrectable input error, the control program releases the 
buffer when the next READ macro is issued on the same DECB, unless you use 
the FRBjEDBUF macro. 
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To effect the release, you must specify the address of the DECB that was used 
when the block was read using the dynamic buffering option and the address of 
the DCB associated with the data set being processed. 
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A partitioned data set is stored only on a direct access device. It is divided into 
sequentially organized members, each composed of one or more records (see 
Figure 44). Each member has a unique name, 1 to 8 characters long, stored in a 
directory that is part of the data set. The records of a given member are written 
or retrieved sequentially. 
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Figure 44. A Partitioned Data Set 


The main advantage of using a partitioned data set is that, without searching the 
entire data set, you can retrieve any individual member after the data set is 
opened. For example, in a program library that is always a partitioned data set, 
each member is a separate program or subroutine. The individual members can 
be added or deleted as required. When a member is deleted, the member name is 
removed from the directory, but the space used by the member cannot be reused 
until the data set is reorganized; that is, compressed using the IEBCOPY utility. 

The directory, a series of 256-byte records at the beginning of the data set, 
contains an entry for each member. Each directory entry contains the member 
name and the starting location of the member within the data set, as shown in 
Figure 44. In addition, you can specify as many as 62 bytes of information in 
the entry. The directory entries are arranged by name in alphameric collating 
sequence. 
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The starting location of each member is recorded by the system as a relative track 
address (from the beginning of the data set) rather than as an absolute track 
address. Thus, an entire data set that has been compressed, can be moved 
without changing the relative track addresses in the directory. The data set can 
be considered as one continuous set of tracks regardless of where the space was 
actually allocated. 

If there is not sufficient space available in the directory for an additional entry, or 
not enough space available within the data set for an additional member, or no 
room on the volume for additional extents, no new members can be stored. A 
directory can not be extended and a partitioned data set may not cross a volume 
boundary. 



Partitioned Data Set Directory 

The directory of a partitioned data set occupies the beginning of the area 
allocated to the data set on a direct access volume. It is searched and maintained 
by the BLDL, FIND, and STOW macros. The directory consists of member 
entries arranged in ascending order according to the binary value of the member 
name or alias. 

Member entries vary in length and are blocked into 256-byte blocks. Each block 
contains as many complete entries as will fit in a maximum of 254 bytes; any 
remaining bytes are left unused and are ignored. Each directory block contains a 
2-byte count field that specifies the number of active bytes in a block (including 
the count field). As shown in Figure 45, each block is preceded by a 
hardware-defined key field containing the name of the last member entry in the 
block, that is, the member name with the highest binary value. 


Count 



Bytes 


Key 

Name of 
Last 

Entry in 
Block 


8 


Data 


Number of 
Bytes Used 
(Maximum 
256) 

Member 

Entry A 

Member 
Entry B 


Member 
Entry N 

x Unused;:*: 

\ s _ _y 

v . 



y 

V 


-V —- 



2 


254 




Figure 45. A Partitioned Data Set Directory Block 


Each member entry contains a member name or an alias. Each entry also 
contains the relative track address of the member and a count field, as shown in 
Figure 46 on page 133. In addition, it may contain a user data field. The last 
entry in the last directory block has a name field of maximum binary value—all 
Ts. 
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Figure 46. A Partitioned Data Set Directory Entry 


NAME 

specifies the member name or alias. It contains as many as 8 alphameric 
characters, left-justified, and padded with blanks if necessary. 


TTR 

is a pointer to the first block of the member. TT is the number of the 
track, relative to the beginning of the data set, and R is the number of the 
block, relative to the beginning of that track. 

Note: This pointer is created by adding 1 to the TTR for the last block of 
the previous member (which is an end-of-file mark). If track TT is full, the 
next block will begin at record 1 of track TT + 1, and the pointer will be 
updated accordingly. The control program finds the block by searching in 
multitrack mode using TT(R-l) as a search argument. 


C 

specifies the number of halfwords contained in the user data field. It may 
also contain additional information about the user data field, as shown 
below: 

Bits 0 1—2 3-7 


0 when set to 1, indicates that the NAME field contains an alias. 

1-2 specifies the number of pointers to locations within the member. 

The operating system supports a maximum of three pointers in the 
user data field. Additional pointers may be contained in a record 
referred to as a note list, discussed below. The pointers can be 
updated automatically if the data set is moved or copied by a utility 
program such as IEHMOVE. The data set must be marked 
unmovable under the following conditions: 
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• More than three pointers are used in the user data field. 

• The pointers in the user data field or note list do not conform to 
the standard format. 

Note: A note list for a partitioned data set containing variable 
length records does not conform to standard format. 

• Variable-length records contain BDWs and RDWs that are 
treated as TTRXs by IEHMOVE. 

• The pointers are not placed first in the user data field. 

• Any direct access address (absolute or relative) is embedded in 
any data blocks or in another data set that refers to this data set. 

3-7 contains a binary value indicating the number of halfwords of user 
data. This number must include the space used by pointers in the 
user data field. 

You can use the user data field to provide variable data as input to the STOW 
macro. If pointers to locations within the member are provided, they must be 4 
bytes long and placed first in the user data field. The user data field format is as 
follows: 



User Data 


TTRN 

TTRN 

TTRN 

Optional 


TT is the relative track address of the note list or area to which you are pointing. 
R is the relative block number on that track. 

N is a binary value that indicates the number of additional pointers contained 
in a note list pointed to by the TTR. If the pointer is not to a note list, 

N = 0. 


A note list consists of additional pointers to blocks within the same member of a 
partitioned data set. You can divide a member into subgroups and store a 
pointer to the beginning of each subgroup in the note list. The member may be 
a load module containing many control sections (CSECTs), each CSECT being a 
subgroup pointed to by an entry in the note list. You get the pointer to the 
beginning of the subgroup by using the NOTE macro after you write the first 
record of the subgroup. Remember that the pointer to the first record of the 
member is stored in the directory entry by the system. 


If the existence of a note list was indicated as shown above, the list can be 
updated automatically when the data set is moved or copied by a utility program 
such as IEHMOVE. Each 4-byte entry in the note list has the following format: 


TTRX 
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TT is the relative track address of the area to which you are pointing. 

R is the relative block number on that track. 

X is available for any use. 

To place the note list in the partitioned data set, you must use the WRITE 
macro. After checking the write operation, use the NOTE macro to determine 
the address of the list and place that address in the user data field of the directory 
entry. 

Note: The linkage editor builds a note list for the load modules in overlay 
format. The addresses in the note list point to the overlay segments that are read 
into the system separately. 


Allocating Space for a Partitioned Data Set 

What is the average size of the members to be stored on your direct access 
volume? How many members will fit on the volume? Will you need directory 
entries for the member names only or will aliases be used? How many? Will 
members be added or replaced frequently? All these questions must be answered 
if you are to estimate your space requirements accurately and use the space 
efficiently. Note, too, that a partitioned data set cannot extend beyond one 
volume. 

If your data set will be large, or if you expect to update it extensively, it might be 
best to allocate a full volume. If it will be small or seldom subject to change, you 
should make your estimate as accurate as possible to avoid wasted space or 
wasted time used for re-creating the data set . 

If the average member length is close to or less than the track length or if the 
track length exceeds 32760 bytes, the most efficient use of the direct access 
storage space may be made with a block size of 1/3 or 1/2 the track length. For 
example, BLKSIZE = 23200 for a 3380 disk will yield two blocks per track. You 
might then ask for either 75 tracks, or 5 cylinders, thus allowing for 3480000 
bytes of data. 

Each member in a data set and each alias need one directory entry apiece. If you 
expect to have 10 members (10 directory entries) and an average of 3 aliases for 
each member (30 directory entries), allocate space for at least 40 directory entries. 

Assuming an average length of 70000 bytes for each member, you need space for 
at least 50 directory entries. If each member also has an average of three aliases, 
space for an additional 150 directory entries is required. 

Space for the directory is expressed in 256-byte blocks. Each block contains from 
3 to 21 entries, depending on the length of the user data field. If you expect 200 
directory entries, request at least 40 blocks. Any unused space on the last track 
of the directory is wasted unless there is enough space left to contain a block of 
the first member. 
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Either of the following space specifications would cause the same size allocation 
for a 3380 disk: 

SPACE=(CYL,(5,,10)) 

SPACE=(TRK,(75,,10)) 

The following example would result in allocation of 100 tracks for data, plus 1 
track for directory space: 

SPACE=(23200,(100,,10)) 

Although a secondary allocation increment has been omitted in these examples, it 
could have been supplied to provide for extension of the member area. The 
directory size, however, cannot be extended. 


Creating a Partitioned Data Set 

If you have no need to add entries to the directory, that is, the STOW macro will 
not be used, you can create a new data set and write the first member as follows 
(see Figure 47): 

• Code DSORG = PS or DSORG = PSU in the DCB macro. 

• Indicate in the DD statement that the data is to be stored as a member of a 
new partitioned data set, that is, DSNAME = name (membemame) and 
DISP = NEW. 

• Request space for the member and the directory in the DD statement. 

• Process the member with an OPEN macro, a series of PUT or WRITE 
macros, and then a CLOSE macro instruction. A STOW macro is issued 
automatically when the data set is closed. 

As a result of these steps, the data set and its directory are created, the records of 
the member are written, and a 12-byte entry is made in the directory. 


//PDSDD DD ---,DSNAME=MASTFILE(MEMBERK),SPACE=(TRK,(100,5,7)), 

DISP=(NEW,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=80)- 


OUTAREA 
| QUTDCB 


OPEN 

(OUTDCB,(OUTPUT)) 


PUT 

OUTDCB,OUTAREA 

Write record to member 

CLOSE 

(OUTDCB) 

Automatic STOW 

DS’ 

CL80 

Area to write from 

DCB 

DS0RG=PS,DDNAME=PDSDD,MACRF=PM 


Figure 47. Creating One Member of a Partitioned Data Set 
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To add additional members to the data set, follow the same procedure. However, 
a separate DD statement (with the space request omitted) is required for each 
member. The disposition should be specified as modify, DISP = MOD. The 
data set must be closed and reopened each time a new member is specified on the 
DD statement. 

To take full advantage of the STOW macro, and thus the BLDL and FIND 
macros, in future processing, you can provide additional information with each 
directory entry. You do this by using the basic partitioned access technique, 
which also allows you to process more than one member without closing and 
reopening the data set, as follows (see Figure 48 on page 138). 

• Request space in the DD statement for the entire data set and the directory. 

• Define DSORG= PO or DSORG = POU in the DCB macro. 

• Use WRITE and CHECK to write and check the member records. 

• Use NOTE to note the location of any note list written within the member, 
if there is a note list, or to note the location of subgroups if there are any. 

• When all the member records have been written, issue a STOW macro 
instruction to enter the member name, its location pointer, and any 
additional data in the directory. The STOW macro writes an end-of-file 
mark after the member. 

• Continue to write, check, note, and stow until all the members of the data set 
and the directory entries have been written. 
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| //PDSDD DD 


--,DSN=MASTFILE,DISP=MOD,SPACE=(TRK,(100,5,7)) 




OPEN (OUTDCB,(OUTPUT)) 

LA STOWREG,STOWLIST Load address of STOW list 


| ** WRITE MEMBER RECORDS AND NOTE LIST 

| MEMBER WRITE DECBX,SF,OUTDCB,OUTAREA WRITE first record of member 
| CHECK DECBX 

j LA NOTEREG,NOTELIST Load address of NOTE list 

WRITE DECBY,SF,OUTDCB,OUTAREA WRITE and CHECK next record 
CHECK DECBY 

JU 

NOTE OUTDCB To divide the member into subgroups, 

ST Rl,Q(NOTEREG) NOTE the TTRN of the first record in 

* the subgroup, storing it in the 

* NOTE list. 

LA NOTEREG,4(NOTEREG) Increment to next NOTE list entry 

WRITE DECBZ,SF,OUTDCB,NOTELIST WRITE NOTE list record at the 

* end of the member 

CHECK DECBZ 

NOTE OUTDCB NOTE TTRN of NOTE list record 

ST Rl, £2(STOWREG) Store TTRN in STOW list 

STOW OUTDCB,(STOWREG),A Enter the information in directory 

* for this member after all records 

* and NOTE lists are written. 

LA STOWREG,16(STOWREG) Increment to the next STOW list entry 


Repeat from label "MEMBER" for each additional member 


CLOSE (OUTDCB) (NO automatic STOW) 


OUTAREA DS CL80 Area to write from 

| OUTDCB DCB ---,DS0RG=P0,DDNAME=PDSDD,MACRF=W 

R1 EQU 1 Register one, return register from NOTE 

NOTEREG EQU 4 Register to address NOTE list 

NOTELIST DS OF NOTE list 

DS F NOTE list entry (4 byte TTRN) 

| DS 19F one entry per subgroup 

STOWREG EQU 5 Register to address STOW list 

STOWLIST DS OF List of member names for STOW 

DC CL8 , MEMBERA f Name of member 

DS CL3 TTR of first record (created by STOW) 

DC X f 23 f C byte, 1 user TTRN, 4 bytes of user data 

DS CL4 TTRN of NOTE list 

... one list entry per member (16 bytes each) 


Figure 48. Creating Members of a Partitioned Data Set Using STOW 
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Processing a Member of a Partitioned Data Set 


Because a member of a partitioned data set is sequentially organized, it is 
processed in the same manner as a sequential data set. Either the basic or 
queued access technique can be used. However, you cannot alter the directory 
when using the queued technique. 

To locate a member or to process the directory, several macros are provided by 
the operating system. The BLDL macro can be used to read one or more 
directory entries into virtual storage; the FIND macro locates a member of the 
data set and positions the DCB for subsequent processing; the STOW macro 
adds, deletes, replaces, or changes a member name in the directory. To use these 
macros, you must specify DSORG= PO or POU in the DCB macro. Before 
issuing FIND, BFDL, or STOW macro, you must check all preceding 
input/output operations for completion. 


BLDL—Construct a Directory Entry List 

The BLDL macro reads one or more directory entries into virtual storage. The 
member names are placed in a BLDL list that is constructed before the BLDL 
macro is issued. For each member name in the list, the system supplies the 
address of the member and any additional information contained in the directory 
entry. Note that, if there is more than one member name in the list, the member 
names must be in collating sequence, regardless of whether the members are from 
the same library or from different libraries. 

You can optimize retrieval time by directing a subsequent FIND macro 
instruction to the BLDL list rather than to the directory to locate the member to 
be processed. 

The BLDL list, as shown in Figure 49 on page 140, must be preceded by a 
4-byte list description that indicates the number of entries in the list and the 
length of each entry (12 to 76 bytes). The first 8 bytes of each entry contain the 
member name or alias. The next 6 bytes contain the TTR, K, Z, and C fields. 

If there is no user data entry, only the TTR and C fields are required. If 
additional information is to be supplied from the directory, as many as 62 bytes 
can be reserved. 

FIND—Position to a Member 

To determine the starting address of a specific member, you must issue a FIND 
macro. The system places the correct address in the data control block so that a 
subsequent input or output operation begins processing at that point. 

There are two ways you can direct the system to the right member when you use 
the FIND macro. Specify the address of an area containing the name of the 
member or specify the address of the TTR field of the entry in a BLDL list you 
have created by using the BLDL macro. In the first case, the system searches the 
directory of the data set for the relative track address; in the second case, no 
search is required, because the relative track address is in the BLDL list entry. 
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(Each entry starts on halfword boundary) 


List 

Description 


FFLL 

Filled in by BLDL 


Member 

Name (C) 

TTR 

(3) 

K 

(1) 

Z 

(1) 

c 

(1) 

i r 

User C 
(C Halfv 

)ata 

i/ords) 

i 



























----■—* 



Programmer supplies: 

FF Number of member entries in list. 

LL Even number giving byte length of each entry (minimum of 12). 
Member name Eight bytes, left-justified. 


\ BLDL supplies: 

\ \ TTR 

\ \ K 


c 

User data 


Member starting location. 

If single data set = 0. If concatenation = number. 

Not required if no user data. 

Source of directory entry. Private library = 0. 

Link library = 1. Job or step library = 2. 

Not required if no user data. 

Sanje C field from directory. Gives number of user data halfwords. 
As much as will fit in entry. 


Figure 49. BLDL List Format 


The system will also search a concatenated series of directories when (1) a DCB 
is supplied that is opened for a concatenated partitioned data set or (2) a DCB is 
not supplied, in which case either JOBLIB or STEPLIB (themselves perhaps 
concatenated) followed by LINKLIB is searched. 

If you want to process only one member, you can process it as a sequential data 
set (DSORG= PS) using either BSAM or QSAM. You indicate the name of the 
member you want to process and the name of the partitioned data set in the 
DSNAME parameter of the DD statement. When you open the data set, the 
system places the starting address in the data control block so that a subsequent 
GET or READ macro begins processing at that point. You cannot use the 
FIND, BLDL, or STOW macro when you are processing one member as a 
sequential data set. 

Because the DCBRELAD address in the data control block is updated when the 
FIND macro is used, you should not issue the FIND macro after WRITE and 
STOW processing without first closing the data set and reopening it for INPUT 
processing. 
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STOW—Update the Directory 


When you add more than one member to a partitioned data set, you must issue a 
STOW macro after writing each member so that an entry for each one will be 
added to the directory. To use the STOW macro, DSORG = PO or POU must 
be specified in the DCB macro. 

You can also use the STOW macro to delete, replace, or change a member name 
in the directory and store additional information with the directory entry. 

Because an alias can also be stored in the directory the same way, you should be 
consistent in altering all names associated with a given member. For example, if 
you replace a member, you must delete related alias entries or change them so 
that they point to the new member. An alias cannot be stored in the directory 
unless the member is present. 

If you add only one member to a partitioned data set and indicate the member 
name in the DSNAME parameter of the DD statement, it is not necessary for 
you to use BPAM and a STOW macro in your program. If you want to do so, 
you may use BPAM and STOW, or BSAM or QSAM. If you use a sequential 
access method, or if you use BPAM and issue a CLOSE macro without issuing a 
STOW macro, the system will issue a STOW macro instruction using the 
member name you have specified on the DD statement. When the system issues 
the STOW, the directory entry that is added is the minimum length (12 bytes). 
This automatic STOW macro will not be issued if the CLOSE macro is a 
TYPE = T or if the TCB indicates the task is being abnormally terminated when 
the DCB is being closed. The DISP parameter on the DD statement determines 
what directory action parameter will be chosen by the system for the STOW 
macro. 

If DISP - NEW or MOD was specified, a STOW macro with the add option will 
be issued. If the member name on the DD statement is not present in the data 
set directory, it will be added. If the member name is already present in the 
directory, the task will be abnormally terminated. 

If DISP = OLD was specified, a STOW macro with the replace option will be 
issued. The member name will be inserted into the directory, either as an 
addition, if the name is not already present, or as a replacement, if the name is 
present. 

Thus, with an existing data set, you should use DISP = OLD to force a member 
into the data set; you should use DISP = MOD to add members with protection 
against the accidental destruction of an existing member. 


Retrieving a Member of a Partitioned Data Set 

To retrieve a specific member from a partitioned data set, either the basic or the 
queued access technique can be used as follows (see Figure 50 on page 142): 

• Code DSORG = PS or DSORG= PSU in the DCB macro. 
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• Indicate in the DD statement that the data is a member of an existing 
partitioned data set by coding DSNAME = name(membemame) and 
DISP = OLD. 

• Process the member with an OPEN macro, a series of GET and READ 
macros, and then a CLOSE macro instruction. 


//PDSDD DD ---,DSN=MASTFILE(MEMBERK),DISP=OLD 


OPEN (INDCB) Open for input, automatic FIND 

GET INDCB,INAREA Read member record 

CLOSE (INDCB) 


INAREA DS 
| INDCB DCB 


CL80 Area to read into 

---,DSORG=PS,DDNAME=PDSDD,MACRF=GM 


Figure 50. Retrieving One Member of a Partitioned Data Set 


ft When your program is executed, the directory is searched automatically and the 

location of the member is placed in the DCB. 

To process several members without closing and reopening, or to take advantage 

of additional data in the directory, this technique should be used (see Figure 51): 

• Code DSORG= PO or POU in the DCB macro. 

• Indicate in the DD statement the data set name of the partitioned data set by 
coding DSNAME = name and DISP=OLD. 

• Issue the BLDL macro to get the list of member entries you need from the 
directory. 

• Use the FIND or POINT macro to prepare for reading the member records. 

• The records may be read from the beginning of the member, or a note list 
may be read first, to obtain additional locations that point to subcategories 
within the member. 

• Read (and check) the records until all those required have been processed. 

• Point to additional categories, if required, and read the records. 

• Your end-of-data-set (EODAD) routine receives control at the end of each 
member. At that time, you can process the next member or close the data 
set. 

• Repeat this procedure for each member to be retrieved. 
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//PDSDD DD - - -,DSN=MASTFILE,DISP=OLD 


OPEN (INDGB) Open for input, no automatic FIND 

LA BLDLREG,BLDLLIST Load address of BLDL list 

BLDL INDCB,BLDLLIST Build a list of selected member 

names in virtual storage 
LA BLDLREG,4(BLDLREG) Point to the first entry 


Read the NOTE list 


MEMBER LA NOTEREG,NOTELIST Load address of NOTE list 

MVC TTRN(4),14(BLDLREG) Move NOTE list TTRN 
* to fullword boundary 

POINT INDCB,TTRN Point to the NOTE list record 

READ DECBX,SF,INDCB,(NOTEREG) Read the NOTE list 
CHECK DECBX 


Read data from a subgroup 

SUBGROUP POINT INDCB,(NOTEREG) Point to subgroup - 

READ DECBY,SF,INDCB,INAREA Read record in subgroup 
CHECK DECBY 

LA NOTEREG,4(NOTEREG) Increment to next subgroup TTRN 


Repeat from label “SUBGROUP” for each additional subgroup 
Repeat from label “MEMBER” for each additional member 


CLOSE (INDCB) 


| INAREA DS CL80 

| INDCB DCB ---,DSORG=PO,DDNAME=PDSDD,MACRF=R 

TTRN DS F TTRN of the NOTE list to point at 

NOTEREG EQU 4 Register to address NOTE list entries 

NOTELIST DS OF NOTE list 

DS F NOTE list entry (4 byte TTRN) 

| DS 19F one entry per subgroup 

BLDLREG EQU 5 Register to address BLDL list entries 

BLDLLIST DS OF List of member names for BLDL 

DC H'lO* Number of entries (10 for example) 

DC H f 18 f Number of bytes per entry 

| DC CL8'MEMBERA' Name of member 

j DS CL3 TTR of first record (created by BLDL) 

DS X Kbyte, concatenation number 

DS X Z byte, location code 

DS X C byte, flag and user data length 

| DS CL4 TTRN of NOTE list 

... one list entry per member (18 bytes each) 

Figure 51. Retrieving Several Members and Subgroups of a Partitioned Data Set 


Chapter 10. Processing a Partitioned Data Set 143 


Modifying a Partitioned Data Set 


Updating a Member of a Partitioned Data Set 

A member of a partitioned data set can be updated in place, or it can be deleted 
and rewritten as a new member. 


Updating in Place 


When you update in place, you read records, process them, and write them back 
to their original positions without destroying the remaining records on the track. 
The following rules apply: 

• You must specify the update option (UPDAT) in the OPEN macro 
instruction. To perform the update, you can use only the READ, WRITE, 
CHECK, NOTE, POINT, FIND, and BLDL macros. 

• You cannot update concatenated partitioned data sets. 

• You cannot use chained scheduling. 

• You cannot delete any record or change its length; you cannot add new 
records. 

A record must be retrieved by a READ macro before it can be updated by a 
WRITE macro. Both macros must be execute forms that refer to the same 
DECB; the DECB must be provided by a list form. (The execute and list forms 
of the READ and WRITE macros are described in Data Administration: Macro 
Instruction Reference.) 

Updating with QSAM: You can update a member of a partitioned data set using 
the locate mode of QSAM (DCB specifies MACRF = PL) and using the PUTX 
macro. The DD statement must specify the data set and member name in the 
DSNAME parameter. This method allows only the updating of the member 
specified in the DD statement. 

Updating with Overlapped Operations: To overlap input/output and processor 
activity, you can start several read or write operations before checking the first for 
completion. You cannot overlap read and write operations, however, as 
operations of one type must be checked for completion before operations of the 
other type are started or resumed. Note that each outstanding read or write 
operation requires a separate channel program and a separate DECB. If a single 
DECB were used for successive read operations, only the last record read could 
be updated. 

In Figure 52 on page 145, overlap is achieved by having a read or write request 
outstanding while each record is being processed. Note the use of the execute 
and list forms of the READ and WRITE macros, identified by the operands 
MF = E and MF = L. 
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//PDSDD DD 


DSNAME=MASTFILE(MEMBERK),DISP=OLD,- 


UPDATDCB DCB 
READ 
READ 

AREAA DS 
AREAB DS 


DSORG=PS,DDNAME=PDSDD,MACRF=(R,W),NCP=2,EODAD=FINISH 
DECBA,SF,UPDATDCB,AREAA,MF=L Define DECBA 

DEGBB,SF,UPDATDCB,AREAB,MF=L Define DECBB 

- Define buffers 


OPEN 

LA 

LA 

READRECD READ 
NEXTRECD READ 
CHECK 


(UPDATDCB,UPDAT) 

2, DECBA 

3, DECBB 

(2) ,SF,MF=E 

(3) ,SF,MF=E 

( 2 ) 


(If update is required, branch to R2UPDATE) 

LR 4,3 

LR 3,2 

LR 2,4 

B NEXTRECD 


Open for update 
Load DECB addresses 

Read a record 

Read the next record 

Check previous read operation 


If no update is required, 
switch DECB addresses in 
registers 2 and 3 
and loop 


In the foUowing statements, ’ R.2’ and ' R3 ? refer to the records that were read using the DECBs whose 
addresses are in registers 2 and 3, respectively. Either register may point to either DECBA or DECBB. 


R2UPDATE CALL 
CHECK 
WRITE 


UPDATE,((2)) 
(3) 

(2),SF,MF=E 


(If R3 requires an update, branch to R3UPDATE) 


CHECK 

B 

R3UPDATE CALL 
WRITE 
CHECK 
CHECK 
B 

FINISH CLOSE 


( 2 ) 

READRECD 
UPDATE,((3)) 
(3),SF,MF=E 
( 2 ) 

(3) 

READRECD 

(UPDATDCB) 


Call routine to update R2 
Check read for next record 
(R3) Write updated R2 


If R3 requires no update, 

check write for R2 and loop 

Call routine to update R3 

Write updated R3 

Check write for R2 

Check write for R3 

Loop 

End-of-Data exit routine 


Figure 52. Updating a Member of a Partitioned Data Set 


Rewriting a Member 

There is no actual update option that can be used to add or extend records in a 
partitioned data set. If you want to extend or add a record within a member, you 
must rewrite the complete member in another area of the data set. Because space 
is allocated when the data set is created, there is no need to request additional 
space. Note, however, that a partitioned data set must be contained on one 
volume. If sufficient space has not been allocated, the data set must be 
reorganized by the IEBCOPY utility program. 

When you rewrite the member, you must provide two DCBs, one for input and 
one for output. Both DCB macros can refer to the same data set, that is, only 
one DD statement is required. 
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You can reflect the change in location of the member either automatically, by 
indicating a disposition of OLD, or by using the STOW macro. Although the 
old member is, in effect, deleted, its space cannot be reused until the data set is 
reorganized. 

If an out-of-space condition occurs when updating a PDS member, the error 
recovery procedure will STOW the PDS member as TEMPNAME’. The 
original member will remain intact. 


Processing a Partitioned Data Set Residing on MSS 

If OPT CD = H is specified in the DCB subparameter of a DD statement, it 
specifies that, if a partitioned data set is being opened for input and resides on an 
MSS device, then at OPEN time the data set is staged to EOF on the virtual 
DASD device. If the option is not specified, only the directory is staged at 
OPEN time and cylinder faults occur during processing. This option might be 
used with the IEBCOPY utility program opening the PDS to reorganize and 
compress the data space. This BPAM option, OPTCD = H, may only be coded 
on the DD statement. 


Concatenating Partitioned Data Sets 

Two or more partitioned data sets can be automatically retrieved by the system 
and processed successively as a single data set. This reading technique is known 
as concatenation. Data sets with like characteristics are those that may be 
processed correctly using the same data control block (DCB), input/output block 
(IOB), and channel program. Any exception makes them unlike. 


Partitioned Concatenation 

When partitioned data sets are concatenated, the system treats the group as a 
single data set and only one data extent block (DEB) is constructed. The 
maximum number of partitioned data sets that can be concatenated is 123 extents 
(input data sets only). For example, 123 single extent data sets can be 
concatenated but 8 data sets each with 16 extents cannot be concatenated. 

Concatenated partitioned data sets are always treated as having like attributes and 
use the attributes of the first data set only. 

You process a concatenation of partitioned data sets the same way you process a 
single partitioned data set with one exception: you must use the FIND macro to 
begin processing a member; you cannot use the POINT (or NOTE) macro until 
after the FIND macro has been issued. Figure 51 on page 143 shows how to 
process a single partitioned data set using FIND. If two members of different 
data sets in the concatenation have the same name, the FIND macro determines 
the address of the first one in the concatenation. You would not be able to 
process the second one in the concatenation. The BLDL macro provides the 
concatenation number of the data set to which the member belongs in the K field 
of the BLDL list. (See “BLDL—Construct a Directory Entry List ,, on 
page 139.) 
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Reading a BPAM Directory Sequentially 


You can read a BPAM directory sequentially just by opening the data set to its 
beginning (without using positioning macros) and reading it. 

• The DD statement should identify the DSNAME without a member name. 
You should specify a disposition option of either OLD or SHR. 

• You can use either BSAM or QSAM with MACRF = R or G. 

• Specify BLKSIZE = 256 and RECFM = F. 

• You must test for the last directory entry (XTFFFFFFF'). 

• If you also want to read the keys (the name of the last member in that 
block), use BSAM and specify KEYLEN= 8. 
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Chapter 11. Processing a Direct Data Set 


In a direct data set, there is a relationship between a control number or 
identification of each record and its location on the direct access volume. This 
relationship allows you to gain access to a record without an index search. You 
determine the actual organization of the data set. If the data set has been 
carefully organized, location of a particular record takes less time than with an 
indexed sequential data set. 

The DSORG parameter of the DCB macro specifies the type of processing to be 
performed; DSORG in the DD statement specifies the organization of the data 
set when it is created. 

Although you can process a direct data set sequentially using either the queued 
access technique or the basic access technique, you cannot read record keys using 
the queued access technique. When you use the basic access technique, each unit 
of data transmitted between virtual storage and an I/O device is regarded by the 
system as a record. If, in fact, it is a block, you must perform any blocking or 
deblocking required. For that reason, the LRECL field is not used when 
processing a direct data set. Only BLKSIZE must be specified when you read, 
add, or update records on a direct data set. 

If dynamic buffering is specified for your direct data set, the system will provide a 
buffer for your records. If dynamic buffering is not specified, you must provide a 
buffer for the system to use. 

As indicated in the discussion of direct access devices, record keys are optional. If 
they are specified, they must be used for every record and must be of a fixed 
length. 


Direct Data Set Organization 

In developing the organization of your data set, you can use direct addressing. 
When direct addresses are used, the location of each record in the data set is 
known. 

If format-F records with keys are being written, the key of each record can be 
used to identify the record. For example, a data set with keys ranging from 0 to 
4999 should be allocated space for 5000 records. Each key relates directly to a 
location that you can refer to as a relative record number. Therefore, each record 
should be assigned a unique key. If identical keys are used, it is possible, during 
periods of high processor and channel activity, to skip the desired record and 
retrieve the next record on the track. The main disadvantage of this type of 


Chapter 11 . Processing a Direct Data Set 149 





organization is that records may not exist for many of the keys even though space 
has been reserved for them. 

Space could be allocated on the basis of the number of records in the data set 
rather than on the range of keys. This type of organization requires the use of a 
cross-reference table. When a record is written in the data set, you must note the 
physical location as a relative block number, an actual address, or as a relative 
track and record number. The addresses must then be stored in a table that is 
searched when a record is to be retrieved. Disadvantages are that 
cross-referencing can be used efficiently only with a small data set, storage is 
required for the table, and processing time is required for searching and updating 
the table. 

A more common, but somewhat complex, technique for organizing the data set 
involves the use of indirect addressing. In indirect addressing, the address of each 
record in the data set is determined by a mathematical manipulation of the key. 
This manipulation is referred to as randomizing or conversion. Because a 
number of randomizing procedures could be used, no attempt is made here to 
describe or explain those that might be most appropriate for your data set. 


Creating a Direct Data Set 

After the organization of a direct data set has been determined, the process of 
creating it is almost identical to that of creating a sequential data set. The BSAM 
DCB macro should be used with the WRITE macro instruction (the form used 
to create a direct data set). The following parameters must be specified in the 
DCB macro instruction: 

• DSORG=PS or PSU 

• DEVD = DA or omitted 

• MACRF = WL 

The DD statement must indicate direct access (DSORG= DA or DAU). If keys 
are used, a key length (KEYLEN) must also be specified. Record length 
(LRECL) need not be specified but may be used to provide compatibility with 
sequential access method processing of this data set. 

It is possible to create a direct data set using QSAM (no keys allowed) or BSAM 
(with or without keys and the DCB specifies MACRF = W). However, this 
method is not recommended because, when you access this direct data set, you 
cannot request a function that requires the information in the capacity record 
(RO) data field. For example, the following restrictions would apply: 

• Variable-length, undefined-length, or variable-length spanned record 
processing is not allowed. 

• The WRITE add function with extended search for fixed-length records (with 
or without track overflow) is not allowed. 
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If a VIO data set is opened for processing with the extended search option, the 
DEBENDCC and DEBENDHH fields of the DEB will reflect the real address of 
the last record written during the BDAM create step. This prevents BDAM from 
searching unused tracks. The information needed to determine the data set size is 
written in the DSCB during the close of the DCB used in the create step. 
Therefore, if this data set is being created and processed by the same program, 
and the DCB used for creating the data set has not been closed before opening 
the DCB to be used for processing, the resultant beginning and ending CCHH 
will be equal. 

If a direct data set is created and updated or read within the same job step, and 
the QPTCD parameter is used in the creation, updating, or reading of the data 
set, different DCBs and DD statements should be used. 

If you are using direct addressing with keys, you can reserve space for future 
format-F records by writing a dummy record. To reserve or truncate a track for 
format-U, format-V, or format-VS records, write a capacity record. The capacity 
record (RO) contains a 7-byte data field (CCHHRLL), where CCHHR is the ID 
of the last record on the track, and LL is the number of unused bytes on the 
track. If a WRITE SZ macro is issued for a track with no records, R is zero and 
LL is the entire length of the track. 

Format-F records are written sequentially as they are presented. When a track is 
filled, the system automatically writes the capacity record and advances to the 
next track. Because of the form in which relative track addresses are recorded, 
direct data sets whose records are to be identified by means other than actual 
address must be limited in size to no more than 65 536 tracks for the entire data 
set. 

Tape-to-Disk— Direct Data Set: In the example problem in Figure 53 on 
page 152, a tape containing 204-byte records arranged in key sequence is used to 
create a direct data set. A 4-byte binary key for each record ranges from 1000 to 
8999, so space for 8000 records is requested. 
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//DAOUTPUT DD DSNAME=SLATE.INDEX.WORDS,DCB=(DSORG=DA, C 

// BLKSIZE=200,KEYLEN=4,RECFM=F),SPACE=(204,8000),--- 


//TAPINPUT DD 


DIRECT 

START 



L ' 

9,=F'1000' 


OPEN 

(DALOAD,(OUTPUT),TAPEDCB) 


LA 

10,COMPARE 

NEXTREC 

GET 

TAPEDCB 


LR 

2,1 

COMPARE 

C 

9,0(2) Compare key of input against 

* 


control number 


BNE 

DUMMY 


WRITE 

DECB1,SF,DALOAD,(2) Write data record 


CHECK 

DECB1 


AH 

9,=H'l' 


B 

NEXTREC 

DUMMY 

C 

9,=F'8999' Have 8000 records been written? 


BH 

ENDJOB 


WRITE 

DECB2,SD,DALOAD,DUMAREA Write dummy 


CHECK 

DECB2 


AH 

9,=H'l' 


BR 

10 

INPUTEND 

LA 

10,DUMMY 


BR 

10 

ENDJOB 

CLOSE 

(TAPEDCB,,DALOAD) 

DUMAREA 

DS* 

8F 

DALOAD 

DCB 

DS0RG=PS,MACRF=(WL),DDNAME=DAOUTPUT, 

DEVD=DA,SYNAD=CHECKER,-— 

TAPEDCB 

DCB 

EODAD=INPUTEND,MACRF=(GL), --- 


Figure 53. Creating a Direct Data Set 


Referring to a Record in a Direct Data Set 

After you have determined how your data set is to be organized, you must 
consider how the individual records will be referred to when the data set is 
updated or new records are added. The record identification can be represented 
in any of the following forms: 

Relative Block Address: You specify the relative location of the record (block) 
within the data set as a 3-byte binary number. This type of reference can be used 
only with format-F records. The system computes the actual track and record 
number. The relative block address of the first block is 0. 

Relative Track Address: You specify the relative track as a 2-byte binary 
number and the actual record number on that track as a 1-byte binary number. 
The relative track address of the first track is 0. 
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Relative Track or Block Address and Actual Key: In addition to the relative 
track or block address, you specify the address of a virtual storage location 
containing the record key. The system computes the actual track address and 
searches for the record with the correct key. 

Actual Address: You supply the actual address in the standard 8-byte 
form—MBBCCHHR. Remember that the use of an actual address may force 
you to indicate that the data set is unmovable. 

Extended Search: You request that the system begin its search with a specified 
starting location and continue for a certain number of records or tracks. This 
same option can be used to request a search for unused space where a record can 
be added. 

To use the extended search option, you must indicate in the DCB (DCBLIMCT) 
the number of tracks (including the starting track) or records (including the 
starting record) that are to be searched. If you indicate a number of records, the 
system may actually examine more than this number. In searching a track, the 
system searches the whole track (starting with the first record); it therefore may 
examine records that precede the starting record or follow the ending record. 

If the DCB specifies a number equal to or greater than the number of tracks 
allocated to the data set or the number of records within the data set, the entire 
data set is searched in the attempt to satisfy your request. 

Exclusive Control for Updating: When more than one task is referring to the 
same data set, exclusive control of the block being updated is required to prevent 
simultaneous reference to the same record. Rather than issuing an ENQ macro 
each time you update a block, you can request exclusive control through the 
MACRF field of the DCB and the type operand of the READ macro. The 
coding example in Figure 55 on page 156 illustrates the use of exclusive control. 
After the READ macro is executed, your task has exclusive control of the block 
being updated. No other task in the system requesting access to the block is 
given access until the operation started by your WRITE macro is complete. If, 
however, the block is not to be written, you can release exclusive control using 
the RELEX macro. 

Feedback Option: This option specifies that the system is to provide the address 
of the record requested by a READ or WRITE macro. This address may be in 
the same form that was presented to the system in the READ or WRITE macro, 
or as an 8-byte actual address. This option can be specified in the OPTCD 
parameter of the DCB and in the READ or WRITE macro. If this option is 
omitted from the DCB but is requested in a READ or WRITE macro, an 8-byte 
actual address is returned to the user. 

The feedback option is automatically provided for a READ macro instruction 
requesting exclusive control for updating. This feedback will be in the form of an 
actual address (MBBCCHHR) unless feedback was specified in the OPTCD field 
of the DCB. In this case, feedback is returned in the format of the addressing 
scheme used in the problem program (an actual or a relative address). When a 
WRITE or RELEX macro is issued (which releases the exclusive control that 
was gotten for the READ request), the system will assume that the addressing 
scheme used for the WRITE or RELEX macro is in the same format as the 
addressing scheme used for feedback in the READ macro. 
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Adding or Updating Records on a Direct Data Set 


The techniques for adding records to a direct data set depend on the format of 
the records and the organization used. 

Format-F With Keys: Adding a record amounts to essentially an update by 
record identification. The reference to the record can be made by either a relative 
block address or a relative track address. 

If you want to add a record passing a relative block address, the system converts 
the address to an actual track address. That track is searched for a dummy 
record, and if one is found the new record is written in place of it. If there is no 
dummy record on the track, you are informed that the write operation did not 
take place. If you request the extended search option, the new record will be 
written in place of the first dummy record found within the search limits you 
specify. If none is found, you are notified that the write operation could not take 
place. In the same way, a reference by relative track address causes the record to 
be written in place of a dummy record on the referenced track or the first within 
the search limits, if requested. If extended search is used, the search begins with 
the first record on the track. Without extended search, the search may start at 
any record on the track. Therefore, records that were added to a track are not 
necessarily located on the track in the same sequence they were written in. 

Format-F Without Keys: Here too, adding a record is really updating a dummy 
record already in the data set. The main difference is that dummy records cannot 
be written automatically when the data set is created. You will have to use your 
own method for flagging dummy records. The update form of the WRITE 
macro (MACRF = W) must be used rather than the add form (MACRF = WA). 

You will have to retrieve the record first (using a READ macro instruction), test 
for a dummy record, update, and write. 

Format-V or Format-U With Keys: The technique used to add records in this 
case depends on whether records are located by indirect addressing or a 
cross-reference table. If indirect addressing is used, you must at least initialize 
each track (write a capacity record) even if no data is actually written. That way 
the capacity record indicates how much space is available on the track. If a 
cross-reference table is used, you should exhaust the input and then initialize 
enough succeeding tracks to contain any additions that might be required. 

To add a new record, use a relative track address. The system examines the 
capacity record to see if there is room on the track. If there is, the new record is 
written. Under the extended search option, the record is written in the first 
available area within the search limit. 

Format- V or Format-U Without Keys: Because a record of this type does not 
have a key, you can access the record only by its relative track or actual address 
(direct addressing only). When you add a record to this data set, you must retain 
the relative track or actual address data (for example, by updating your 
cross-reference table). The extended search option is not allowed because it 
requires keys. 
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Tape-to-Disk Add—Direct Data Set: The example in Figure 54 on page 155 
involves adding records to the data set created in the last example. Notice that 
the write operation adds the key and the data record to the data set. If the 
existing record is not a dummy record, an indication is returned in the exception 
code of the DECB. For that reason, it is better to use the WAIT macro instead 
of the CHECK macro to test for errors or exceptional conditions. 


//DIRADD 

DD 

DSNAME=SLATE.INDEX.WORDS,— 

//TAPEDD 

DD 

— 

DIRECTAD 

START 



OPEN 

(DIRECT,(OUTPUT),TAPEIN) 

NEXTREC 

GET 

TAPEIN,KEY 


L 

4,KEY Set up relative record number 


SH 

4,=H'1000' 


ST 

4, REF 


WRITE 

DECB,DA,DIRECT,DATA,'S',KEY,REF+1 


WAIT 

ECB=DECB 


CLC 

DECB+1(2),=X'0000' Check for any errors 


BE 

NEXTREC 


Check error bits and take required action 

DIRECT DCB DDNAME=DIRADD,DSORG=DA,RECFM=F,KEYLEN=4,BLKSIZE=200, C 

MACRF=(WA) 

TAPEIN DCB 

KEY DS F 

DATA DS CL200 

REF DS F 


Figure 54. Adding Records to a Direct Data Set 


Tape-to-Disk Update—Direct Data Set: The example in Figure 55 is similar to 
that in Figure 54, but involves updating rather than adding. There is no check 
for dummy records. The existing direct data set contains 25000 records whose 
5-byte keys range from 00001 to 25000. Each data record is 100 bytes long. The 
first 30 characters are to be updated. Each input tape record consists of a 5-byte 
key and a 30-byte data area. Notice that only data is brought into virtual storage 
for updating. 

When you are updating variable-length records, you should use the same length 
to read and write a record. 
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//DIRECTDD DD 

DSNAME=SLATE.INDEX.WORDS, - - - 

//TAPINPUT DD 

— 

DIRUPDAT 

START 



OPEN 

(DIRECT,(UPDAT).TAPEDCB) 

NEXTREC 

GET 

TAPEDCB,KEY 


PACK 

KEY,KEY 


CVB 

3,KEYFIELD 


SH 

3,=H'1' 


ST 

3, REF 


READ 

DECBRD,DIX,DIRECT,'S',’S',0,REF+1 


CHECK 

DECBRD 


L 

3.DECBRD+12 


MVC 

0(30,3),DATA 


ST 

3.DECBWR+12 


WRITE 

DECBWR,DIX,DIRECT,'S','S',0,REF+1 


CHECK 

DECBWR 


B 

NEXTREC 

KEYFIELD 

DS’ 

0D 


DC 

XL3'0' 

KEY 

DS 

CL5 

DATA 

DS 

CL30 

REF 

DS 

F 

DIRECT 

DCB 

DS0RG=DA,DDNAME=DIRECTDD,MACRF=(RISXC,WIC), 


0PTCD=RF,BUFN0=1,BUFL=100 

TAPEDCB 

DCB 

— 


Figure 55. Updating a Direct Data Set 


Consideration for User Labels: User labels, if wanted, must be created when the 
data set is created. They may be updated, but not added or deleted, during 
processing of a direct data set. When creating a multivolume direct data set using 
BSAM, you should turn off the header exit entry after OPEN and turn on the 
trailer label exit entry just before issuing the CLOSE. This eliminates the 
end-of-volume exits. The first volume, containing the user label track, must be 
mounted when the data set is closed. If you have requested exclusive control, 
OPEN and CLOSE will ENQ and DEQ to prevent simultaneous reference to 
user labels. 

Consideration for using the 2305-2 Fixed Head Storage: When a data set on a 
2305-2 device is to be used by several tasks simultaneously, or when overlapping 
I/O (successive writes issued without an intervening CHECK or WAIT) is used, 
the following combination may produce overlaying of records: 

• WRITE-add processing 

• Fixed records with or without track overflow 
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Sharing Direct Data Sets 


BDAM permits several tasks to share the same DCB and several jobs to share 
the same data set. It synchronizes I/O requests at both levels by maintaining a 
read-exclusive list. 

When several tasks share the same DCB and each asks for exclusive control of 
the same block, BDAM issues a system ENQ for the block (or in some cases the 
whole track). It reads in the block and passes it to the first caller while putting 
all subsequent requests for that block on a wait queue. When the first task 
releases the block, BDAM moves it into the next caller's buffer and posts it 
complete. The block is passed to subsequent callers in the order the request was 
received. 

BDAM not only synchronizes the I/O requests, but also issues only one ENQ 
and one I/O request for several read requests for the same block. 

Note: Because BDAM processing is not sequential and I/O requests are not 
related, a caller can continue processing other blocks while waiting for exclusive 
control of the shared block. 

Because BDAM issues a system ENQ for each record held exclusively, it allows a 
data set to be shared between jobs, so long as all callers use BDAM. BDAM's 
commonly understood argument is what is enqueued on. 

BDAM supports multiple task users of a single DCB when working with existing 
data sets. When operating in load mode, however, only one task may use the 
DCB at a time. The following restrictions and comments apply when more than 
one task shares the same DCB, or when using multiple DCBs for the same data 
set. 

• Subpool 0 must be shared. * 

• The user should ensure that a WAIT or CHECK macro has been issued for 
all outstanding BDAM requests before the task issuing the READ or 
WRITE macro terminates. In case of abnormal termination, this can be 
done through a STAE/STAI or ESTAE exit. 

• FREEDBUF and/or RELEX macros should be issued to free any resources 
that could still be held by the terminating task. This can be done during or 
after task termination. 

Note: Open, close, and all I/O must be performed in the same key and state 
(problem state or supervisor state). 
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Chapter 12. Processing an Indexed Sequential Data Set 


The organization of an indexed sequential data set allows you a great deal of 
flexibility in the operations you can perform. The data set can be read or written 
sequentially, individual records can be processed in any order, records can be 
deleted, and new records can be added. The system automatically locates the 
proper position in the data set for new records and makes any necessary 
adjustments when records are deleted. 

The queued access technique must be used to create an indexed sequential data 
set. It can also be used to sequentially process or update the data set and to add 
records to the end of the data set. The basic access technique can. be used to 
insert new records between records already in the data set and to update the data 
set directly. 


Indexed Sequential Data Set Organization 

The records in an indexed sequential data set are arranged according to collating 
sequence by a key field in each record. Each block of records is preceded by a 
key field that corresponds to the key of the last record in the block. 

An indexed sequential data set resides on direct access storage devices and can 
occupy as many as three different areas: 

• Prime Area —This area, also called the prime data area, contains data records 
and related track indexes. It exists for all indexed sequential data sets. 

• Overflow Area —This area contains records that overflow from the prime area 
when new data records are added. It is optional. 

• Index Area —This area contains master and cylinder indexes associated with 
the data set. It exists for a data set that has a prime area occupying more 
than one cylinder. 

The indexes of an indexed sequential data set are analogous to the card catalog in 
a library. For example, if you know the name of the book or the author, you 
can look in the card catalog and obtain a catalog number that will enable you to 
locate the book in the book files. You then go to the shelves and proceed 
through rows until you find the shelf containing the book. Usually each row 
contains a sign to indicate the beginning and ending numbers of all books in that 
particular row. Thus, as you proceed through the rows, you compare the catalog 
number obtained from the index with the numbers posted on each row. Upon 
locating the proper row, you search that row for the shelf that contains the book. 
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Then you look at the individual book numbers on that shelf until you find the 
particular book. 

ISAM uses the indexes in much the same way to locate records in an indexed 
sequential data set. 

As the records are written in the prime area of the data set, the system accounts 
for the records contained on each track in a track index area. Each entry in the 
track index identifies the key of the last record on each track. There is a track 
index for each cylinder in the data set. If more than one cylinder is used, the 
system develops a higher-level index called a cylinder index. Each entry in the 
cylinder index identifies the key of the last record in the cylinder. To increase the 
speed of searching the cylinder index, you can request that a master index be 
developed for a specified number of cylinders, as shown in Figure 56. 

Rather than reorganize the whole data set when records are added, you can 
request that space be allocated for additional records in an overflow area. 

Prime Area 

Records are written in the prime area when the data set is created or updated. 

The last track of prime data is reserved for an end-of-file mark. The portion of 
Figure 56 labeled Cylinder 1 illustrates the initial structure of the prime area. 
Although the prime area can extend across several noncontiguous areas of the 
volume, all the records are written in key sequence. Each record must contain a 
key; the system automatically writes the key of the highest record before each 
block. 
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When the ABSTR option of the SPACE parameter of the DD statement is used 
to generate a multivolume prime area, the VTOC of the second volume and on 
all succeeding volumes must be contained within cylinder 0 of the volume. 


Index Areas 


The operating system generates track and cylinder indexes automatically. As 
many as three levels of master index are created if requested. 


Track Index 


This is the lowest level of index and is always present. There is one track index 
for each cylinder in the prime area; it is written on the first track(s) of the cylinder 
that it indexes. 

The index consists of a series of paired entries, that is, of a normal entry and an 
overflow entry for each prime track. For fixed-length records, each normal entry 
(and also DCBFIRSH) points to either record 0 or the first prime record on a 
shared track (a track shared by index and data). For variable-length records, the 
normal entry contains the key of the highest record on the track and the address 
of the last record on the track. The overflow entry is originally the same as the 
normal entry. (This is why 100 appears twice on the track index for cylinder 1 in 
Figure 56.) The overflow entry is changed when records are added to the data 
set. Then the overflow entry contains the key of the highest overflow record and 
the address of the lowest overflow record logically associated with the track. 

Figure 57 on page 162 shows the format of a track index. 

If all the tracks allocated for the prime data area are not used, the index entries 
for the unused ones are flagged as inactive. The last entry of each track index is a 
dummy entry indicating the end of the index. When fixed-length record format 
has been specified, the remainder of the last track of each cylinder used for a track 
index contains prime data records if there is room for them. 
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key of the highest record on the prime data track 
address of the prime data track 

key of the highest overflow record logically associated with the prime data track 
address of the lowest overflow record logically associated with the prime data track 


Notes: 

• If there are no overflow records, overflow key and data entries are the same as normal key and data entries. 

• This figure is a logical representation only; that is, it makes no attempt to show the physical size of track index entries. 

Figure 57. Format of Track Index Entries 


Each index entry has the same format as the others. It is an unblocked, 
fixed-length record consisting of a count, a key, and a data area. The length of 
the key corresponds to the length of the key area in the record to which it points. 
The data area is always 10 bytes long. It contains the full address of the track or 
record to which the index points, the level of the index, and the entry type. 

Cylinder Index 

For every track index created, the system generates a cylinder index entry. There 
is one cylinder index for a data set that points to a track index. Because there is 
one track index per cylinder, there is one cylinder index entry for each cylinder in 
the prime data area, except in the case of a 1-cylinder prime area. As with track 
indexes, inactive entries are created for any unused cylinders in the prime data 
area. 

Master Index 


As an optional feature, the operating system creates, at your request, a master 
index. The presence of this index makes long, serial searches through a large, 
cylinder index unnecessary. 

You can specify the conditions under which you want a master index created. 
For example, if you have specified NTM = 3 and OPTCD = M in your DCB 
macro, a master index is created when the cylinder index exceeds 3 tracks. The 
master index consists of one entry for each track of cylinder index. If your data 
set is extremely large, a higher-level master index is created when the first-level 
master index exceeds three tracks. This higher-level master index consists of one 
entry for each track of the first-level master index. This procedure can be 
repeated for as many as three levels of master index. 
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Overflow Areas 


As records are added to an indexed sequential data set, space is required to 
contain those records that will not fit on the prime data track on which they 
belong. You can request that a number of tracks be set aside as a cylinder 
overflow area to contain overflows from prime tracks in each cylinder. An 
advantage of using cylinder overflow areas is a reduction of search time required 
to locate overflow records. A disadvantage is that there will be unused space if 
the additions are unevenly distributed throughout the data set. 

Instead of, or in addition to, cylinder overflow areas, you can request an 
independent overflow area. Overflow from anywhere in the prime data area is 
placed in a specified number of cylinders reserved solely for overflow records. An 
advantage of having an independent overflow area is a reduction in unused space 
reserved for overflow. A disadvantage is the increased search time required to 
locate overflow records in an independent area. 

If you request both cylinder overflow and independent overflow, the cylinder 
overflow area is used first. It is a good practice to request cylinder overflow areas 
large enough to contain a reasonable number of additional records and an 
independent overflow area to be used as the cylinder overflow areas are filled. 


Creating an Indexed Sequential Data Set 

You can create an indexed sequential data set in one step or in several steps. 

You can create the data set either by writing all records in a single step or by 
writing one group of records in one step and writing additional groups of records 
in subsequent steps. Writing records in subsequent steps is called resume loading. 
When using either one step or several steps, you must present the records for 
writing in ascending order by key. 

To create an indexed sequential data set by the one-step method, you should 
proceed as follows: 

• Code DSORG= IS or DSORG=ISU and MACRF = PM or MACRF = PL 
in the DCB macro. 

• Specify in the DD statement the DCB attributes DSORG= IS or 
DSORG= ISU, record length (LRECL), blocksize (BLKSIZE), record 
format (RECFM), key length (KEYLEN), relative key position (RKP), 
options required (OPTCD), cylinder overflow (CYLOFL), and the number 
of tracks for a master index (NTM). Specify space requirements with the 
SPACE parameter. To reuse previously allocated space, omit the SPACE 
parameter and code DISP = (OLD, KEEP). 

• Open the data set for output. 

• Use the PUT macro to place all the records or blocks on the direct access 
volume. 

• Close the data set. 
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The records that comprise a newly created data set must be presented for writing 
in ascending order by key. You can merge two or more input data sets. If you 
want a data set with no records (a null data set), you must write at least one 
record when you create the data set. You can subsequently delete this record to 
achieve the null data set. 

If an unload is done that deletes all existing records in an ISAM data set, at least 
one record must be written on the subsequent load. If no record is written, the 
data set will be unusable. 

If the records are blocked, you should not write a record with a hexadecimal 
value of FF and a key of hexadecimal value FF. This value is used for padding. 
If it occurs as the last record of a block, the record cannot be retrieved. If the 
record is moved to the overflow area, it is lost. 

When creating an indexed sequential data set, a procedure called loading, you can 
improve performance by using the full-track-index write option. You do this by 
specifying OPTCD = U in the DCB. This causes the operating system to 
accumulate track index entries in virtual storage. Note that the full-track-index 
write option can be used only for fixed-length records. 

If you do not specify full-track-index write, the operating system writes each 
normal overflow pair of entries for the track index after the associated prime data 
track has been written. If you do specify full-track-index write, the operating 
system accumulates track index entries in virtual storage until either (a) there are 
enough entries to fill a track or (b) end-of-data or end-of-cylinder is reached. 

Then the operating system writes these entries as a group, writing one group for 
each track of track index. This option requires allocation of more storage space 
(the space in which the track index entries are gathered), but the number of I/O 
operations required to write the index can be significantly decreased. 

When you specify the full-track-index write option, the track index entries are 
written as fixed-length unblocked records. If the area of virtual storage available 
is not large enough the entries are written as they are created, that is, in normal 
overflow pairs. 

After an indexed sequential data set has been created, its characteristics cannot be 
changed. However, for added flexibility, the system allows you to retrieve records 
by using either the queued access technique with simple buffering or the basic 
access technique with dynamic buffering. 

Tape-to-Disk—Indexed Sequential Data Set: The example in Figure 58 on 
page 165 shows the creation of an indexed sequential data set from an input tape 
containing 60-character records. The key by which the data set is organized is in 
positions 20 through 29. The output records will be an exact image of the input, 
except that the records will be blocked. One track per cylinder is to be reserved 
for cylinder overflow. Master indexes are to be built when the cylinder index 
exceeds 6 tracks. Reorganization information about the status of the cylinder 
overflow areas is to be maintained by the system. The delete option will be used 
during any future updating. 
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//INDEXDD DD 

DSNAME=SLATE.DICT(PRIME),DCB=(BLKSIZE=240,CYL0FL=1, 

// 


DS0RG=IS,OPTCD=MYLR, 

RECFM=FB,LRECL=60,NTM=6,RKP=19, 



KEYLEN=10),UNIT=3330 

,SPACE=(CYL,25,,C0NTIG),--- 

//INPUTDD DD 

— 


ISLOAD 

START 

0 



DCBD 

DS0RG=IS 


ISLOAD 

CSECT 




OPEN 

(IPDATA,,ISDATA,(OUTPUT)) 

NEXTREC 

GET 

IPDATA 

Locate mode 


LR 

0,1 

Address of record in register 


PUT 

ISDATA,(0) 

Move mode 


B 

NEXTREC 


CHECKERR 

l' ' 

3,=A(ISDATA) 

Initialize base for errors 


USING 

IHADCB,3 



TM 

DCBEXCDljX 1 04' 



BO 

OPERR 

Uncorrectable error 


TM 

DCBEXCD1,X'20' 



BO 

NOSPACE 

Space not found 


TM 

DCBEXCD2,X'80 1 



BO 

SEQCHK 

Record out of sequence 


Rest of error checking 
Error routine 

End of job routine (EODAD FOR IPDATA) 

IPDATA DCB 

ISDATA DCB DDNAME=INDEXDD,DSORG=IS,MACRF=(PM),SYNAD=CHECKERR 

Figure 58. Creating an Indexed Sequential Data Set 


To create an indexed sequential data set in more than one step, create the first 
group of records using the one-step method described above. This first section 
must contain at least one data record. The remaining records can then be added 
to the end of the data set in subsequent steps, using resume load. Each group to 
be added must contain records with successively higher keys. This method allows 
you to create the indexed sequential data set in several short time periods rather 
than in a single long one. 

This method also allows you to provide limited recovery from uncorrectable 
output errors. When an uncorrectable output error is detected, do not attempt to 
continue processing or to close the data set. If you have provided a SYNAD 
routine, it should issue the ABEND macro to terminate processing. If no 
SYNAD routine is provided, the control program will terminate your processing. 
If the error shows that space in which to add the record was not found, you must 
close the data set; issuing subsequent PUT macros can cause unpredictable 
results. You should begin recovery at the record following the end of the data as 
of the last successful close. The rerun time is limited to that necessary to add the 
new records, rather than to that necessary to re-create the whole data set. 

When you extend an indexed sequential data set with resume load, the 
disposition parameter of the DD statement must specify MOD. To ensure that 
the necessary control information is in the DSCB before attempting to add 
records, you should at least open and close the data set successfully on a version 
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of the system that includes resume load. This is necessary only if the data set was 
created on a previous version of the system. Records may be added to the data 
set by resume load until the space allocated for prime data in the first step has 
been filled. 

During resume load on a data set with a partially filled track and/or a partially 
filled cylinder, the track index entry and/or the cylinder index entry is overlaid 
when the track or cylinder is filled. Resume load for variable-length records 
begins at the next sequential track of the prime data set. If resume load 
abnormally terminates after these index entries have been overlaid, a subsequent 
resume load will result in a sequence check when it adds a key that is higher than 
the highest at the last successful CLOSE but lower than the key in the overlaid 
index entry. When the SYNAD exit is taken for a sequence check, register 0 
contains the address of the high key of the data set. However, if the SYNAD exit 
is taken during CLOSE, register 0 will contain the IOB address. 

Allocating Space for an Indexed Sequential Data Set 

An indexed sequential data set has three areas: prime, index, and overflow. Space 
for these areas can be subdivided and allocated as follows: 

• Prime area—If you request a prime area only, the system automatically uses a 
portion of that space for indexes, taking one cylinder at a time as needed. 

Any unused space in the last cylinder used for index will be allocated as an 
independent overflow area. More than one volume can be used in most 
cases, but all volumes must be for devices of the same device type. 

• Index area— You can request that a separate area be allocated to contain your 
cylinder and master indexes. The index area must be contained within one 
volume, but this volume can be on a device of a different type than the one 
that contains the prime area volume. If a separate index area is requested, 
you cannot catalog the data set with a DD statement. 

If the total space occupied by the prime area and index area does not exceed 
one volume, you can request that the separate index area be embedded in the 
prime area (to reduce access arm movement) by indicating an index size in 
the SPACE parameter of the DD statement defining the prime area. 

If you request space for prime and index areas only, the system automatically 
uses any space remaining on the last cylinder used for master and cylinder 
indexes for overflow, provided the index area is on a device of the same type 
as the prime area. 

• Overflow urea—Although you can request an independent overflow area, it 
must be contained within one volume and must be of the same device type as 
the prime area. If no specific request for index area is made, then it will be 
allocated from the specified independent overflow area. 
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To request that a designated number of tracks on each cylinder be used for 
cylinder overflow records, you must use the CYLOFL parameter of the DCB 
macro. The number of tracks that you can use on each cylinder equals the 
total number of tracks on the cylinder minus the number of tracks needed for 
track index and for prime data, that is: 

Overflow tracks = total tracks 

- (track index tracks + prime data tracks) 

Note that, when you create a 1-cylinder data set, ISAM reserves 1 track on the 
cylinder for the end-of-file filemark. You may not request an independent index 
for an ISAM data set that has only 1 cylinder of prime data. 

When you request space for an indexed sequential data set, the DD statement 
must follow a number of conventions, as shown below and summarized in 
Figure 59 on page 167. 

• Space can be requested only in cylinders, SPACE = (CYL,(...)), or absolute 
tracks, SPACE = (ABSTR,(...)). If the absolute track technique is used, the 
designated tracks must make up a whole number of cylinders. 

• Data set organization (DSORG) must be specified as indexed sequential (IS 
or ISU) in both the DCB macro and the DCB parameter of the DD 
statement. 

• All required volumes must be mounted when the data set is opened; that is, 
volume mounting cannot be deferred. 

• If your prime area extends beyond one volume, you must indicate the 
number of units and volumes to be spanned; for example, 

UNIT = (3380,3), VOLUME - (,„3). 

• You can catalog the data set using the DD statement parameter 

DISP= (,CATLG) only if the entire data set is defined by one DD statement; 
that is, if you did not request a separate index or independent overflow area. 

As your data set is created, the operating system builds the track indexes in the 
prime data area. Unless you request a separate index area or an embedded index 
area, the cylinder and master indexes are built in the independent overflow area. 

If you did not request an independent overflow area, the cylinder and master 
indexes are built in the prime area. 

If an error is encountered during allocation of a multivolume data set, the 
IEHPROGM utility program should be used to scratch the DSCBs of the data 
sets that were successfully allocated. The IEHLIST utility program can be used 
to determine whether or not part, of the data set has been allocated. The 
IEHLIST utility program is also useful to determine whether space is available or 
whether identically named data sets exist before space allocation is attempted for 
indexed sequential data sets. These utility programs are described in Utilities . 
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1. Number 
of DD 

Statements 

Criteria 

2. Types 
of DD 
Statements 

3. Index 
Size 

Coded? 

Restrictions on 

Unit Types and 
Number of Units 
Requested 

Resulting Arrangement of Areas 

3 

INDEX 

PRIME 

OVFLOW 


None 

Separate index, prime, and overflow 
areas. 

2 

INDEX 

PRIME 


None 

Separate index and prime areas. Any 
partially used index cylinder is used for 
independent overflow if the index and 
prime areas are on the same type of 
device. 

2 

PRIME 

OVFLOW 

No 

None 

Prime area and overflow area with an 
index at its end. 

2 

PRIME 

OVFLOW 

Yes 

The statement 
defining the 
prime area 
cannot request 
more than one 
unit. 

Prime area and embedded index, and 
overflow area. 

1 

PRIME 

No 

None 

Prime area with index at its end. Any 
partially used index cylinder is used for 
independent overflow. 

1 

PRIME 

Yes 

Statement 
cannot request 
more than one 
unit. 

Prime area with embedded index area; 
independent overflow in remainder of 
partially used index cylinder. 


Figure 59. Requests for Indexed Sequential Data Sets 

Specifying a Prime Data Area 

To request that the system allocate space and subdivide it as required, you should 
code: 

//ddname DD DSNAME~dsname,DCB=DSORG==IS, 

// SPACE=(CYL 3 quantity,,CONTIG),UNIT=unitname, 

// DISP=(,KEEP),- 

You can accomplish the same type of allocation by qualifying your dsname with 
the element indication (PRIME). This element is assumed if omitted. It is 
required only if you request an independent index or overflow area. To request 
an embedded index area when an independent overflow area is specified, you 
must indicate DSNAME = dsname (PRIME). To indicate the size of the 
embedded index, you specify SPACE = (CYL,(quantity„index size)). 
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Specifying a Separate Index Area 

To request a separate index area, other than an embedded area as described 
above, you must use a separate DD statement. The element name is specified as 
(INDEX). The space and unit designations are as required. Notice that only the 
first DD statement can have a data definition name. The data set name (dsname) 
must be the same. 

//ddname DD DSNAME=dsname(INDEX) 3 - 

// DD DSNAME=dsname(PRIME),-• 

Specifying an Independent Overflow Area 

A request for an independent overflow area is essentially the same as for a 
separate index area. Only the element name, OVFLOW, is changed. If you do 
not request a separate index area, only two DD statements are required. 

//ddname DD DSNAME=dsname(INDEX), 

// DD DSNAME=dsname(PRIME),- 

// DD DSNAME=dsname(OVFLOW),- 

Calculating Space Requirements for an Indexed Sequential Data Set 

To determine the number of cylinders required for an indexed sequential data set, 
you must consider the number of blocks that will fit on a cylinder, the number of 
blocks that will be processed, and the amount of space required for indexes and 
overflow areas. When you make the computations, consider how much 
additional space is required for device overhead. Figure 68 on page 219 and 
Figure 69 on page 220 show device capacities and overhead formulas. In the 
formulas that follow, the length of the last (or only) block, shown below as Bn, 
must include device overhead as given in Figure 69. 

Blocks = Track capacity / Length of blocks 

The following eight steps summarize calculation of space requirements for an 
indexed sequential data set. 

Note: Use modulo-32 arithmetic when calculating key length and data length 
terms in your equations. Compute these terms first, then round up to the nearest 
increment of 32 bytes before completing the equation. 

Step 1: After you know how many records will fit on a track and the maximum 
number of records you expect to create, you can determine how many tracks you 
will need for your data. 

Number of = (Maximum number of blocks 

tracks required / Blocks per track) + 1 

ISAM load mode reserves the last prime data track for the file mark. 

Example: Assume that a 200000 record parts-of-speech dictionary is stored on an 
IBM 3380 Disk Storage as an indexed sequential data set. Each record in the 
dictionary has a 12-byte key (the word itself) and an 8-byte data area containing a 
parts-of-speech code and control information. Each block contains 50 records; 
LRECL= 20 and BLKSIZE= 1000. Using the formula from Figure 69 on 
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page 220, we find that each track will contain 26 blocks or 1300 records. A total 

of 155 tracks will be required for the dictionary. V 

Blocks = 47968/(256+((12+267)/32)(32)+((1000+267)/32)(32)) 

= 47968/1824 = 26 

Records per track = (26 blocks)(50 records per block) - 1300 
Prime data 

tracks = (200000 records / 1300 records per track) + 1 = 155 
required 

Step 2: You will want to anticipate the number of tracks required for cylinder 
overflow areas. The computation is the same as for prime data tracks, but you 
must remember that overflow records are unblocked and a 10-byte link field is 
added. Remember also that, if you exceed the space allocated for any cylinder 
overflow area, an independent overflow area is required. Those records are not 
placed in another cylinder overflow area. 

Overflow records = Track capacity / Length of overflow records 
per track 

Example: Approximately 5000 overflow records are expected for the data set 

described in step 1. Because 55 overflow records will fit on a track, 91 overflow 

tracks are required. These are 91 overflow tracks for 155 prime data tracks, or 

approximately 1 overflow track for every 2 prime data tracks. Because the 3380 

disk pack has 15 tracks per cylinder, it would probably be best to allocate 5 

tracks per cylinder for overflow. x ^ 

Overflow = 47968/(256+((12+267)/32)(32)+((30+267)/32)(32)) 
records = 47968/864 
per track = 55 

Overflow = 5000 records / 55 records per track 

tracks =91 

required 

Overflow tracks per cylinder = 5 

Step 3: You will have to set aside space in the prime area for track index entries. 

There will be two entries (normal and overflow) for each track on a cylinder that 
contains prime data records. The data field of each index entry is always 10 bytes 
long. The key length corresponds to the key length for the prime data records. 

How many index entries will fit on a track? 

Index entries = Track capacity / Length of index entries 
per track 

Example: Again assuming a 3380 disk pack and records with 12-byte keys, we 
find that 59 index entries fit on a track. 

Index = 47968/(256+( (12+267)/32) (32)+( (104-267)/32) (32) ) 
entries = 47968/832 
per track =57 

/O 

Yv" 
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Step 4: Unused space on the last track of the track index is a function of the 
number of tracks required for track index entries, which in turn depends upon the 
number of tracks per cylinder and the number of track index entries per track. 
You can use any unused space for any prime data records that will fit. 

Unused = (Number of index entries per track) 
space - (2 (Number of tracks per cylinder 

- Number of overflow tracks per cylinder) + 1) 
(Number of bytes per index) 

Note that, for variable-length records, or when a prime data record will not fit on 
the last track of the track index, the last track of the track index is not shared 
with prime data records. In this case, if the remainder of the division is less than 
or equal to 2, drop the remainder. In all other cases, round the quotient up to 
the next integer. 

Example: The 3380 disk pack has 15 tracks per cylinder. You can fit 57 track 
index entries into one track. Therefore, you need less than 1 track for each 
cylinder. 

Number of 

trk index = (2 (15 - 5) + 1) / (57 + 2) 

trks per =21/59 

cylinder 

The space remaining on the track is 47968 - (21 (832)) = 30496 bytes. 

This is enough space for 16 blocks of prime data records. Because the normal 
number of blocks per track is 26, the blocks use 16/26ths of the track, and the 
effective number of track index tracks per cylinder is therefore 1 - 16/26 or 0.385. 

Note that space is required on the last track of the track index for a dummy entry 
to indicate the end of the track index. The dummy entry consists of an 8-byte 
count field, a key field the same size as the key field in the preceding entries, and 
a 10-byte data field. 

Step 5: Next you have to calculate the number of tracks available on each 
cylinder for prime data records. You cannot include tracks set aside for cylinder 
overflow records. 

Prime data = Tracks per cylinder 

tracks per - Overflow tracks per cylinder 

cylinder - Index tracks per cylinder 

Example: If you set aside 5 cylinder overflow tracks, and you need 0.385ths of a 
track for the track index, 9.615 tracks are available on each cylinder for prime 
data records. 

Prime data tracks = 15 - 5 - (0.385) = 9.615 
per cylinder 

Step 6: The number of cylinders required to allocate prime space is determined 
by the number of prime data tracks required divided by the number of prime data 
tracks available on each cylinder. This area includes space for the prime data 
records, track indexes, and cylinder overflow records. 
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Number of 
cylinders 
needed 


= Prime data tracks needed 

/ Prime data tracks per cylinder needed 


v„y 


Example: You need 155 tracks for prime data records. You can use 9.615 tracks 
per cylinder. Therefore, you need 17 cylinders for your prime area and cylinder 
overflow areas. 

Number of = (155) / (9.615) = 16.121 (round up to 17) 

cylinders 

required 

Step 7: You will need space for a cylinder index and track indexes. There is a 
cylinder index entry for each track index (for each cylinder allocated for the data 
set). The size of each entry is the same as the size of the track index entries; 
therefore, the number of entries that will fit on a track is the same as the number 
of track index entries. Unused space on a cylinder index track is not shared. 

Number of tracks = (Track indexes 4- 1) 

required for / (Index entries per track cylinder index) 

Example: You have 17 track indexes (from Step 6). Because 57 index entries fit 
on a track (from Step 3), you need 1 track for your cylinder index. The 
remaining space on the track is unused. 

Number of tracks required = (17 + 1) / 57 = 18 / 57 = 0.316 < 1 
for cylinder index 

Note that, every time a cylinder index crosses a cylinder boundary, ISAM writes 
a dummy index entry that lets ISAM chain the index levels together. The 
addition of dummy entries can increase the number of tracks required for a given 
index level. To determine how many dummy entries will be required, divide the 
total number of tracks required by the number of tracks on a cylinder. If the 
remainder is 0, subtract 1 from the quotient. If the corrected quotient is not 0, 
calculate the number of tracks these dummy entries require. Also consider any 
additional cylinder boundaries crossed by the addition of these tracks and by any 
track indexes starting and stopping within a cylinder. 

Step 8: If you have a data set large enough to require master indexes, you will 
want to calculate the space required according to the number of tracks for master 
indexes (NTM parameter) you specified in the DCB macro or the DD statement. 

If the cylinder index exceeds the NTM specification, an entry is made in the 
master index for each track of the cylinder index. If the master index itself 
exceeds the NTM specification, a second-level master index is started. As many 
as three levels of master indexes are created if required. 

The space requirements for the master index are computed in the same way as 
those for the cylinder index. 

Calculate the number of tracks for master indexes as follows: 

// Tracks for master indexes = 

(# Cylinder index tracks +1) / Index entries per track 
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If the number of cylinder indexes is greater than NTM, calculate the number of 
tracks for a first level master index as follows: 

# Tracks for first level master index = 

(Cylinder track indexes + 1) / Index entries per track 

If the number of first level master indexes is greater than NTM, calculate the 
number of tracks for a second level master index as follows: 

# Tracks for second level master index = 

(First level master index + 1) / Index entries per track 

If the number of second level master indexes is greater than NTM, calculate the 
number of tracks for a third level master index as follows: 

# Tracks for second level master index = 

(Second level master index + 1) / Index entries per track 

Example: Assume that your cylinder index will require 22 tracks. Because large 
keys are used, only 10 entries will fit on a track. Assuming that NTM was 
specified as 2, 3 tracks will be required for a master index, and two levels of 
master index will be created. 

Number of tracks required =(22+1) / 10 =2.3 
for master indexes 

Note that, every time a master index crosses a cylinder boundary, ISAM writes a 
dummy index entry that lets ISAM chain the index levels together. The addition 
of dummy entries can increase the number of tracks required for a given index 
level. To determine how many dummy entries will be required, divide the total 
number of tracks required by the number of tracks on a cylinder. If the 
remainder is 0, subtract 1 from the quotient. If the corrected quotient is not 0, 
calculate the number of tracks these dummy entries require. Also consider any 
additional cylinder boundaries crossed by the addition of these tracks and by any 
track indexes starting and stopping within a cylinder. 

Summary: Indexed Sequential Space Requirement Calculations 

1. How many blocks will fit on a track? 

Blocks = Track capacity / Length of blocks 

2. How many overflow records will fit on a track? 

Overflow records = Track capacity 

/ Length of overflow records per track 

3. How many index entries will fit on a track? 

Index entries = Track capacity / Length of index entries 
per track 

4. How much space is left on the last track of the track index? 

Unused = (Number of index entries per track) 

space - (2 (Number of tracks per cylinder 

- Number of overflow tracks per cylinder) + 1) 
(Number of bytes per index) 
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5. How many tracks on each cylinder can you use for prime data records? 

Prime data = Tracks per cylinder 
tracks per - Overflow tracks per cylinder 
cylinder - Index tracks per cylinder 

6. How many cylinders do you need for the prime data area? 

Number of = Prime data tracks needed 

cylinders / Prime data tracks per cylinder needed 

needed 

7. How many tracks do you need for the cylinder index? 

Number of tracks 

required for = (Track indexes +1) 

cylinder index / Index entries per track 

8. How many tracks do you need for master indexes? 

Number of tracks 

required for = (Number of cylinder index tracks 4- 1) 

master indexes / Index entries per track 


Retrieving and Updating an Indexed Sequential Data Set 


Sequential Retrieval and Update 

To sequentially retrieve and update records in an indexed sequential data set: 

• Code DSORG= IS or DSORG = ISU to agree with what you specified when 
you created the data set, and MACRF = GL, MACRF = SK, or 
MACRF = PU in the DCB macro. 

• Code a DD statement for retrieving the data set. The data set characteristics 
and options are as defined when the data set was created. 

• Open the data set. 

• Set the beginning of sequential retrieval (SETL). 

• Retrieve records and process as required, marking records for deletion as 
required. 

• Return records to the data set. 

• Use ESETL to end sequential retrieval as required and reset the starting 
point. 

• Close the data set to end all retrieval. 
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Sequential Updates—Indexed Sequential Data Set: Assume that, using the data 
set created in the previous example, you are to retrieve all records whose keys 
begin with 915. Those records with a date (positions 13 through 16) before 
today's date are to be deleted. The date is in the standard form as returned by 
the system in response to the TIME macro instruction, that is, packed decimal 
OOyyddds. Overflow records can be logically deleted even though they cannot be 
physically deleted from the data set. 

One way to solve this problem is shown in Figure 60. 


//INDEXDD 

DD 

DSNAME=SLATE.DICT, 

— 

ISRETR 

START 

0 



DCBD 

DS0RG=IS 


ISRETR 

CSECT 




USING 

IHADCB,3 



LA 

3,ISDATA 



OPEN 

(ISDATA) 



SETL 

ISDATA,KC,KEYADDR 

Set scan limit 


TIME 


Today*s date in register 1 


ST 

1,TODAY 


NEXTREC 

GET 

ISDATA 

Locate mode 


CLC 

19(10,1),LIMIT 



BNL 

ENDJOB 



CP 

12(4,1),TODAY 

Compare for old date 


BNL 

NEXTREC 



MV I 

0 ( 1 ),x' ff' 

Flag old record for 




deletion 


PUTX 

ISDATA 

Return delete record 


B 

NEXTREC 


TODAY 

DS 

F 


KEYADDR 

DC 

C' 915' 

Key prefix 


DC 

XL7'0 * 

Key padding 

LIMIT 

DC 

C* 916' 



DC 

XL7'0 1 


CHECKERR 





Test DCBEXCD1 and DCBEXDE2 for error indication 


Error Routines 


ENDJOB CLOSE (ISDATA) 

ISDATA DCB DDNAME=INDEXDD,DS0RG=IS,MACRF=(GL,SK,PU), C 

SYNAD=CHECKKR 

Figure 60. Sequentially Updating an Indexed Sequential Data Set 
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Direct Retrieval and Update 


v,y 

By using the basic indexed sequential access method (BISAM) to process an 
indexed sequential data set, you can directly access the records in the data set for: 

♦ Direct retrieval of a record by its key 

♦ Direct update of a record 

♦ Direct insertion of new records 

Because the operations are direct, there can be no anticipatory buffering. 

However, if ‘S’ is specified on the READ macro, the system provides dynamic 
buffering each time a read request is made. (See Figure 61 on page 178.) 

To ensure that the requested record is in virtual storage before you start 
processing, you must issue a WAIT or CHECK macro. If you issue a WAIT 
macro, you must test the exception code field of the DECB. If you issue a 
CHECK macro, the system tests the exception code field in the DECB. If an 
error analysis routine has not been specified and a CHECK is issued, and an 
error situation exists, the program is abnormally terminated with a system 
completion code of XX'OT For both WAIT and CHECK, if you want to 
determine whether the record is an overflow record, you should test the exception 
code field of the DECB. 

After you test the exception code field of the DECB, you need not set it to 0. If 

you have used a READ KU macro and if you plan to use the same DECB again V ^ 

to rewrite the updated record using a WRITE K macro, you should not set the 

field to 0. If you do, your record may not be rewritten properly. 

To update existing records, you must use the READ KU and WRITE K 
combination. Because READ KU implies that the record will be rewritten in the 
data set, the system retains the DECB and the buffer used in the READ KU and 
uses them when the record is written. If you decide not to write the record, you 
should use the same DECB in another read or write macro or issue a 
FREEDBUF macro if dynamic buffering was used. If you issue several READ 
KU or WRITE K macros before checking the first one, you may destroy some of 
your updated records unless the records are from different blocks. 

When you are using scan mode with QISAM and you want to issue PUTX, issue 
an ENQ on the data set before processing it and a DEQ after processing is 
complete. ENQ must be issued before the SETL macro, and DEQ must be 
issued after the ESETL macro. When you are using BISAM to update the data 
set, do not modify any DCB fields or issue a DEQ until you have issued 
CHECK or WAIT. 


/Ov 
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Sharing a BISAM DCB between Related Tasks: If there is the possibility that 
your task and another task will be simultaneously accessing the same data set, or 
the same task has two or more DCBs opened for the same data set, you should 
use the DCB integrity feature. You specify the DCB integrity feature by coding 
DISP = SHR in your DD statement. In this way you ensure that the DCB fields 
are maintained for your program to process the data set correctly. If you do not 
use DISP= SHR and more than one DCB is open for updating the data set, the 
results are unpredictable. 

If you specify DISP = SHR, you must also issue an ENQ for the data set before 
each input/output request and a DEQ upon completion of the request. All users 
of the data set must use the same qname and mame operands for ENQ. For 
example, the users might use the data set name as the qname operand. (For 
more information about using ENQ and DEQ, see Supervisor Services and Macro 
Instructions.) 

For subtasking, I/O requests should be issued by the task that owns the DCB or 
a task that will remain active as long as the DCB is open. If the task that issued 
the I/O request terminates, the storage used by its data areas (such as IOBs) may 
be freed or queuing switches in the DCB work area may be left set on, causing 
another task issuing an I/O request to the DCB to program check or to enter the 
wait state. For example, if a subtask issues and completes a READ KU I/O 
request, the IOB created by the subtask is attached to the DCB update queue. If 
that subtask terminates, and subpool zero is not shared with the subtask owning 
the DCB, the IOB storage area is freed and the integrity of the ISAM update 
queue is destroyed. A request from another subtask, attempting to use that 
queue, may cause unpredictable abends. As another example, if a WRITE KEY 
NEW is in process when the subtask terminates, 

’ WRITE-KEY-NEW-IN-PROCESS f bit is left set on. If another I/O request 
is issued to the DCB, the request is queued but cannot proceed. 

Direct Update with Exclusive Control—Indexed Sequential Data Set: In the 
example shown in Figure 61 on page 178, the previously described data set is to 
be updated directly with transaction records on tape. The input tape records are 
30 characters long, the key is in positions 1 through 10, and the update 
information is in positions 11 through 30. The update information replaces data 
in positions 31 through 50 of the indexed sequential data record. 
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//INDEXDD 

DD 

DSNAME=SLATE.DICT,DCB=(DSORG=IS,BUFN0=1, 

//TAPEDD 

DD 



ISUPDATE 

START 

0 


NEXTREC 

GET 

TPDATA,TPRECORD 



ENQ 

(RESOURCE,ELEMENT,E 

, ,SYSTEM) 


READ 

DECBRW,KU,,'S',MF=E 

Read into dynamically 

* 



obtained buffer 


WAIT 

ECB=DECBRW 



TM 

DECBRW+24,X'FD' 

Test for any condition 


BM 

RDCHECK 

but overflow 


L 

3,DECBRW+16 

Pick up pointer to 

* 



record 


MVC 

ISUPDATE-ISRECORD 

Update record 



(L'UPDATE,3),UPDATE 



WRITE 

DECBRW,K,MF=E 



WAIT 

ECB=DECBRW 



TM 

DECBRW+24,X'FD' 

Any errors? 


BM 

WRCHECK 



DEQ 

(RESOURCE,ELEMENT,, 

SYSTEM) 


B 

NEXTREC 


RDCHECK 

TM 

DECBRW+24,X' 80' 

No record found 


BZ 

ERROR 

If not, go to error 

* 



routine 


FREEDBUF 

DECBRW,K,ISDATA 

Otherwise, free buffer 


MVC 

ISKEY,KEY 

Key placed in ISRECORD 


MVC 

ISUPDATE,UPDATE 

Updated information 

* 



placed in ISRECORD 


WRITE 

DECBRW,KN,,WKNAREA, 

'S f ,MF=E Add record to data 

* 



set 


WAIT 

ECB=DECBRW 



TM 

DECBRW+24,X'FD' 

Test for errors 


BM 

ERROR 



DEQ 

(RESOURCE,ELEMENT,, 

SYSTEM) Release exclusive 

* 



control 


B 

NEXTREC 


WKNAREA 

DS 

4F 

BISAM WRITE KN work 

JL 

4 % 



field 

ISRECORD 

DS 

0CL50 

50-byte record from 

JU 



ISDATA 


DS 

CL19 

DCB First part of 

JU 



ISRECORD 


Figure 61 (Part 1 of 2). Directly Updating an Indexed Sequential Data Set 
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ISKEY 

DS 

CLIO 

Key field of ISRECORD 


DS 

CL1 

Part of ISRECORD 

ISUPDATE 

DS 

CL20 

Update area of ISRECORD 


ORG 

ISUPDATE 

Overlay ISUPDATE with 

TPRECORD 

DS 

0CL30 

TPRECORD 30-byte record 

KEY 

DS 

CLIO 

from TPDATA DCB Key 

JU 

UPDATE 

DS 

CL20 

for locating 

ISDATA record update 

RESOURCE 

DC 

CL8'SLATE' 

information or new data 

ELEMENT 

DC 

C’DICT' 



READ 

DECBRW,KU,ISDATA,'S’ , 

t S t ,KEY,MF=L 

ISDATA 

DCB 

DDNAME=INDEXDD,DSORG= 

IS,MACRF=(RUS,WUA), 

TPDATA 

DCB 

MSHI=INDEX,SMSI=2000 

INDEX 

DS 

2000C 


Figure 61 (Fart 2 of 2). 

Directly Updating an Indexed Sequential Data Set 


Exclusive control of the data set is requested, because more than one task may be 
referring to the data set at the same time. Notice that, to avoid tying up the data 
set until the update is completed, exclusive control is released after each block is 
written. 

Note the use of the FREEDBUF macro instruction in Figure 61. Usually, the 
FREEDBUF macro has two functions: 

• To indicate to the ISAM routines that a record that has been read for update 
will not be written back 

• To free a dynamically obtained buffer 

In Figure 61, because the read operation was unsuccessful, the FREEDBUF 
macro frees only the dynamically obtained buffer. 

The first function of FREEDBUF allows you to read a record for update and 
then decide not to update it without performing a WRITE for update. You can 
use this function even when your READ macro does not specify dynamic 
buffering, provided that you have included S (for dynamic buffering) in the 
MACRF field of your READ DCB. 

You can effect an automatic FREEDBUF merely by reusing the DECB, that is, 
by issuing another READ or a WRITE KN to the same DECB. You should 
use this feature whenever possible, because it is more efficient than FREEDBUF. 
For example, in Figure 61, the FREEDBUF macro could be eliminated, because 
the WRITE KN addressed the same DECB as the READ KU. 

For an indexed sequential data set with variable-length records, you may make 
three types of updates by using the basic access technique. You may read a 
record and write it back with no change in its length, simply updating some part 
of the record. You do this with a READ KU followed by a WRITE K, the 
same way you update fixed-length records. 
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Two other methods for updating variable-length records use the WRITE KN 
macro and allow you to change the record length. In one method, a record read 
for update (by a READ KU) may be updated in a manner that will change the 
record length and then be written back with its new length by a WRITE KN. In 
the second method, you may replace a record with another record having the 
same key and possibly a different length using the WRITE KN macro. To 
replace a record, it is not necessary to have first read the record. 

In either method, when changing the record length, you must place the new 
length in the DECBLGTH field of the DECB before issuing the WRITE KN 
macro. If you use a WRITE KN macro to update a variable-length record that 
has been marked for deletion, the first bit (no record found) of the exceptional 
condition code field (DECBEXC1) of the DECB is set on. If this condition is 
found, the record must be written using a WRITE KN with nothing specified in 
the DECBLGTH field. 

Do not try to use the DECBLGTH field to determine the length of a record read, 
because DECBLGTH is for use with writing records, not reading them. If you 
are reading fixed-length records, the length of the record read is in DCBLRECL, 
and if you are reading variable-length records, the length is in the record 
descriptor word (RDW). 

Direct Update—Indexed Sequential Data Set with Variable-Length Records: In 
Figure 62, an indexed sequential data set with variable-length records is updated 
directly with transaction records on tape. The transaction records are of variable 
length and each contains a code identifying the type of transaction. Transaction 
code 1 indicates that an existing record is to be replaced by one with the same 
key; 2 indicates that the record is to be updated by appending additional 
information, thus changing the record length; 3 or greater indicates that the 
record is to be updated with no change to its length. For this example, the 
maximum record length of both data sets is 256 bytes. The key is in positions 6 
through 15 of the records in both data sets. The transaction code is in position 5 
of records on the transaction tape. The work area (REPLAREA) size is equal to 
the maximum record length plus 16 bytes. 
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//INDEXDD 

DD 

DSNAME=SLATE.DICT, 

DCB=(DSORG=IS,BUFNO=l, 

//TAPEDD 

DD 

- — 


ISUPDVLR 

START 

0 


NEXTREC 

GET 

TPDATA,TRANAREA 


JL 

CLI 

TRANCODE,2 

Determine if replacement or 
other transaction 


BL 

REPLACE 

Branch if replacement 


READ 

DECBRW,KU,,'S’,'S’ 

,MF=E Read record for update 


CHECK 

DECBRW,DSORG=IS 

Check exceptional conditions 


CLI 

TRANCODE,2 

Determine if change or append 


BH 

CHANGE 

Branch if change 


* CODE TO MOVE RECORD INTO REPLACEA+16 AND APPEND DATA FROM TRANSACTION 

* RECORD 



MVC 

DECBRW+6(2),REPLAREA+16 

Move new length from RDW 

* 

WRITE 

DECBRW,KN,,REPLAREA,MF=E 

into DECBLGTH (DECB+6) 
Rewrite record with 

* 

CHECK 

DECBRW,DSORG=IS 

changed length 


B 

NEXTREC 


CHANGE 





* CODE TO CHANGE FIELDS OR UPDATE FIELDS OF THE RECORD 



WRITE 

DECBRW,K,MF=E 

Rewrite record with no 

* 

CHECK 

DECBRW,DSORG=IS 

change of length 


B 

NEXTREC 


REPLACE 

MVC 

DECBRW+6(2),TRANAREA 

Move new length from RDW 

* 



into DECBLGTH (DECB+6) 


WRITE 

DECBRW,KN,,TRANAREA- 

16,MF=E Write transaction record 

* 



as replacement for record 

* 

CHECK 

DECBRW,DSORG=IS 

with the same key 


B 

NEXTREC 


CHECKERR 


SYNAD 

routine 

REPLAREA 

DS’ 

CL272 


TRANAREA 

DS 

CL4 


TRANCODE 

DS 

CLI 


KEY 

DS 

CLIO 


TRANDATA 

DS 

CL241 



READ 

DECBRW,KU,ISDATA, ’ S ’ 

,'S',KEY,MF=L 

ISDATA 

DCB 

DDNAME=INDEXDD,DSORG 

=1S,MACRF=(RUSC,WUAC),SYNAD=CHECKERR 

TPDATA 

DCB 

— 


Figure 62. Directly Updating an Indexed Sequential Data Set with Variable-Length Records 
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Adding Records to an Indexed Sequential Data Set 


Either the queued access technique or the basic access technique may be used to 
add records to an indexed sequential data set. A record to be inserted between 
records already in the data set must be inserted by the basic access method using 
WRITE KN (key new). Records added to the end of a data set, that is, records 
with successively higher keys, may be added to the prime data area or the 
overflow area by the basic access method using WRITE KN, or they may be 
added to the prime data area by the queued access technique using the PUT 
macro. 

Inserting New Records into an Existing Indexed Sequential Data Set 

As you add records to an indexed sequential data set, the system inserts each 
record in its proper sequence according to the record key. The remaining records 
on the track are then moved up one position each. If the last record does not fit 
on the track, it is written in the first available location in the overflow area. A 
10-byte link field is added to the record put in the overflow area to connect it 
logically to the correct track. The proper adjustments are made to the track 
index entries. This procedure is illustrated in Figure 63 on page 184. 

Subsequent additions are written either on the prime track or as part of the 
overflow chain from that track. If the addition belongs after the last prime record 
on a track but before a previous overflow record from that track, it is written in 
the first available location in the overflow area. Its link field contains the address 
of the next record in the chain. 

For BISAM, if you add a record that has the same key as a record in the data 
set, a “duplicate record” condition is indicated in the exception code. However, if 
you specified the delete option and the record in the data set is marked for 
deletion, the condition is not reported and the new record replaces the existing 
record. (For more information about exception codes, see Data Administration: 
Macro Instruction Reference.) 


Adding New Records to the End of an Indexed Sequential Data Set 

Records added to the end of a data set, that is, records with successively higher 
keys, may be added by the basic access method using WRITE KN (key new), or 
by the queued access method using the PUT macro instruction (resume load). In 
either case, records may be added to the prime data area. 

When you use the WRITE KN macro, the record being added is placed in the 
prime data area only if there is room for it on the prime data track containing the 
record with the highest key currently in the data set. If there is not sufficient 
room on that track, the record is placed in the overflow area and linked to that 
prime track even though additional prime data tracks originally allocated have not 
been filled. 

When you use the PUT macro (resume load), records are added to the prime 
data area until the space originally allocated is filled. After this allocated prime 
area is filled, you can add records to the data set using WRITE KN, in which 
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case they will be placed in the overflow area. Resume load is discussed in more 
detail under “Creating an Indexed Sequential Data Set” on page 163. 

In order to add records with successively higher keys using the PUT macro 
(resume load): 

• The key of any record to be added must be higher than the highest key 
currently in the data set. 

• The DD statement must specify DISP = MOD or the EXTEND option is 
specified in the OPEN macro. 

• The data set must have been successfully closed when it was created or when 
records were previously added using the PUT macro. 

You may continue to add fixed-length records in this manner until the original 
space allocated for prime data is exhausted. 

When you add records to an indexed sequential data set using the PUT macro 
(resume load), new entries are also made in the indexes. During resume load on 
a data set with a partially filled track and/or a partially filled cylinder, the track 
index entry and/or the cylinder index entry is overlaid when the track or cylinder 
is filled. If resume load abnormally terminates after these index entries have been 
overlaid, a subsequent resume load will get a sequence check when adding a key 
that is higher than the highest key at the last successful CLOSE but lower than 
the key in the overlaid index entry. When the SYNAD exit is taken for a 
sequence check, register 0 contains the address of the highest key of the data set. 

Maintaining an Indexed Sequential Data Set 

An indexed sequential data set must be reorganized occasionally for two reasons: 

• The overflow area will eventually be filled. 

• Additions increase the time required to locate records directly. 

The frequency of reorganization depends on the activity of the data set and on 
your timing and storage requirements. There are two ways you can accomplish 
reorganization: 

• You can reorganize the data set in two passes by writing it sequentially into 
another area of direct access storage or magnetic tape and then re-creating it 
in the original area. 

• You can reorganize the data set in one pass by writing it directly into another 
area of direct access storage. In this case, the area occupied by the original 
data set cannot be used by the reorganized data set. 

The operating system maintains statistics that are pertinent to reorganization. 

The statistics, written on the direct access volume and available in the DCB for 
checking, include the mimber of cylinder overflow areas, the number of unused 
tracks in the independent overflow area, and the number of references to overflow 
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Normal Entry Overflow Entry 


Initial Format 

100 i Track 

! 1 

ioo ! Tr 1 ack 

1 1 

200 j TraCk 

_I___ 

200 | Tr | ck 

_1____ 

Track 

Index 





10 

20 

40 

100 

Prime 



Data 


150 

175 

190 

200 










Overflow 







Add Records 
25 and 101 

40 | Tr 1 ack 

1 1 

100 I J rack 3 . 

i Record 1 

l 

190 j T, J* 

| Track 3 
"" ; Record 2 

Track 

Index 




10 

20 

25 

40 

Prime 

Data 




101 

150 

175 

190 






100 j Track 

__l_ 1 _ 

200 i Tr | Ck 

1 ____ 



OverflQw 







Add Records 
26 and 199 

i Track 

26 | 1 

___l_ 1 _i 

i no * Track 3 
,UU 1 Record 3 

_L 

190 ' Tr 2 aCk 

900 ' Track3 
200 j Record 4 

Track 

Index 




10 

20 

_ 25 .J 

26 

Prime 

Data 




101 

150 

175 

190 

Overflow 

100 Tr 1 ack 

200 i Track 

1 ^ 

! Track 3 

40 | Record 1 

iqq ' Track 3 

1 Record 2 


Figure 63. Adding Records to an Indexed Sequential Data Set 


records other than the first. They appear in the RORG1, RORG2, and RORG3 
fields of the DCB. 

If you indicate when creating or updating the data set that you want to be able to 
flag records for deletion during updating, you can set the delete code (the first 
byte of a fixed-length record or the fifth byte of a variable-length record) to 
X f FF f . If a flagged record is forced off its prime track during a subsequent 
update, it will not be rewritten in the overflow area, as shown in Figure 64 on 
page 185, unless it has the highest key on that cylinder. Similarly, when you 
process sequentially, flagged records are not retrieved for processing. During 
direct processing, flagged records are retrieved the same as any other records, and 
you should check them for the delete code. 
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Note that a WRITE KN (key new) to a data set containing variable-length 
records removes all the deleted records from that prime data track. 

Note that, to use the delete option, RKP must be greater than 0 for fixed-length 
records and greater than 4 for variable-length records. 




Initial Format 100 | Track 1 100 | Track 1 200 [ Track 2 200 | Track 2 



Record 100 is 
marked for deletion 
and record 25 is 
added to the 
data set 



Figure 64. Deleting Records from an Indexed Sequential Data Set 
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Indexed Sequential Buffer and Work Area Requirements 


The only case in which you will ever have to compute the buffer length (BUFL) 
requirements for your program occurs when you use the BUILD or GETPOOL 
macro to construct the buffer area. If you are creating an indexed sequential data 
set (using the PUT macro), each buffer must be 8 bytes longer than the block 
size to allow for the hardware count field, that is: 


Buffer length = 8 + Block size 


(8) 

Data 


(BLKSIZE) 


<-Buf f ei-> 


One exception to this formula arises when you are dealing with an unblocked 
format-F record whose key field precedes the data field; its relative key position is 
0 (RKP = 0). In that case, the key length must also be added, that is: 


Buffer length = 8 + Key length + Record length 


(8 ) 

Key 

Data 


(KEYLEN) 

(LRECL) 


<-Buf f ei-> 


The buffer requirements for using the queued access technique to read or update 
(using the GET or PUTX macro) an indexed sequential data set are discussed 
below. 

For fixed-length unblocked records when both the key and data are to be read 
and for variable-length unblocked records, padding is added so that the data will 
be on a doubleword boundary, that is: 

Buffer length = Key length + Padding + 10 + Block size 


Key 


ISAM Link Field 

Data 

(KEYLEN) 

Padding 

(10) 

(BLKSIZE) 


<--Buf f ei-> 


For fixed-length unblocked records when only data is to be read: 

Buffer length = 16 + LRECL 


Padding 

ISAM Link Field 

Data 

(6) 

(10) 

(LRECL) 


<--Buf f ei-> 
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For fixed-length blocked records: 

Buffer length = 16 + Block size 


Padding 

ISAM Link Field 

Data 

(6) 

CIO) 

(BLKSIZE) 


<-Buf fei-> 


For variable-length blocked records, padding is 2 if the buffer starts on a fullword 
boundary that is not also a doubleword boundary or 6 if the buffer starts on a 
doubleword boundary, that is: 

Buffer length = 12 or 16 + Block size 


Padding 

ISAM Link Field 

Data 

C 6 ) 

(10) 

(BLKSIZE) 


<-Buf f ei-> 


If you are using the input data set with fixed-length, unblocked records as a basis 
for creating a new data set, a work area is required. 


The size of the work area is given by: 

Work area = Key length + Record length 


Key 

Data 


(LRECL) 


<_-Work Area--> 


If you are reading only the data portion of fixed-length unblocked records or 
variable-length records, the work area is the same size as the record, that is: 

Work area = Record length 

Data 
(LRECL) 

<----Work Area-> 

When you use the basic access technique to update records in an indexed 
sequential data set, the key length field need not be considered in determining 
your buffer requirements. The area for fixed-length records must be: 

Buffer length = 16 + Block size 


Padding 

ISAM Link Field 

Data 

(6) 

(10) 

(BLKSIZE) 


<-Buf f ei-> 


Chapter 12. Processing an Indexed Sequential Data Set 


187 




















For variable-length records, padding is 2 if the buffer starts on a fullword 
boundary that is not also a doubleword boundary or 6 if a buffer starts on a 
doubleword boundary. Thus, the area must be: 


Buffer length = 12 or 16 + Blocksize 


Padding 

ISAM Link Field 

Data 

(6) 

(10) 

(BLKSIZE) 


<-Buffer-> 


You can save processing time by adding fixed-length or variable-length records to 
a data set by using the MSWA parameter of the DCB macro to provide a special 
work area for the operating system. The size of the work area (SMSW parameter 
in the DCB) must be large enough to contain a full track of data, the count fields 
of each block, and the work space for inserting the new record. 

The size of the work area needed varies according to the record format and the 
device type. You can calculate it during execution using device-dependent 
information obtained with the DEVTYPE macro and data set information from 
the DSCB obtained with the OBTAIN macro. (The DEVTYPE and OBTAIN 
macros are discussed in System-Data Administration.) 

Note that you can use the DEVTYPE macro only if the index and prime areas 
are on devices of the same type or if the index area is on a device with a larger 
track capacity than that of the device containing the prime area. If you are not 
trying to maintain device independence, you may precalculate the size of the 
work area needed and specify it in the SMSW field of the DCB macro. The 
maximum value for SMSW is 65535. 

For calculating the size of the work area, see the storage device capacities shown 
in Figure 68 on page 219 and the device overhead formulas given in “Estimating 
Space Requirements” on page 218. 

For fixed-length blocked records, SMSW is calculated as follows: 

SMSW = (DS2HIRPR) (BLKSIZE + 8) + LRECL + KEYLEN 

The formula for fixed-length unblocked records is 
SMSW = (DS2HIRPR) (KEYLEN + LRECL + 8) + 2 

The value for DS2HIRPR is in the index (format-2) DSCB. Debugging 
Handbook shows the exact location of this field in the index DSCB. If you don't 
use the MSWA and SMSW parameters, the control program supplies a work area 
using the formula BLKSIZE + LRECL + KEYLEN. 

For variable-length records, SMSW may be calculated by one of two methods. 
The first method may lead to faster processing, although it may require more 
storage than the second method. 

The first method is as follows: 

SMSW = DS2HIRPR (BLKSIZE + 8) + LRECL + KEYLEN + 10 
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The second method is as follows: 

SMSW = ( (Trk Cap - Bn + 1) / Block length) (BLKSIZE) 

+ 8 (DS2HIRPR) + LRECL + KEYLEN 
+ 10 + (REM - N - KEYLEN) 

In all the above formulas, the terms BLKSIZE, LRECL, KEYLEN, and SMSW 
are the same as the parameters in the DCB macro (Trk Cap = track capacity). 
REM is the remainder of the division operation in the formula and N is the first 
constant in the block length formulas described in Figure 69 on page 220. 
(REM-N-KEYLEN) is added only if it is positive. 

The second method yields a minimum value for SMSW. Therefore, the first 
method is valid only if its application results in a value higher than the value that 
would be derived from the second method. If neither MSWA nor SMSW is 
specified, the control program supplies the work area for variable-length records, 
using the second method to calculate the size. 

Another technique to increase the speed of processing is to provide space in 
virtual storage for the highest-level index. To specify the address of this area, use 
the MSHI operand of the DCB. When the address of this area is specified, you 
must also specify its size, which you can do by using the SMSI operand of the 
DCB. The maximum value for SMSI is 65535. If you do not use this technique, 
the index on the volume must be searched. If the high-level index is greater than 
65535 bytes in length, your request for the high-level index in storage is ignored. 

The size of the storage area (SMSI parameter) varies. To allocate that space 
during execution, you can find the size of the high-level index in the 
DCBNCRHI field of the DCB during your DCB exit routine or after the data set 
is open. Use the DCBD macro to gain access to the DCBNCRHI field (see 
Chapter 5, “Specifying a Data Control Block and Initializing Data Sets” on 
page 41). You can also find the size of the high-level index in the DS2NOBYT 
field of the index (format 2) DSCB, but you must use the utility program 
IEHLIST to print the information in the DSCB. You can calculate the size of 
the storage area required for the high-level index by using the formula 

SMSI = (Number of Tracks in High-Level Index) 

(Number of Entries per Track) 

(Key Length +10) 

The formula for calculating the number of tracks in the high-level index is in 
“Calculating Space Requirements for an Indexed Sequential Data Set” on 
page 169. When a data set is shared and has the DCB integrity feature 
(DISP = SHR), the high-level index in storage is not updated when DCB fields 
are changed. 

Controlling an Indexed Sequential Data Set Device 

An indexed sequential data set is processed sequentially or directly. Direct 
processing is accomplished by the basic access technique. Because you provide 
the key for the record you want read or written, all device control is handled 
automatically by the system. If you are processing the data set sequentially, using 
the queued access technique, the device is automatically positioned at the 
beginning of the data set. 
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In some cases, you may want to process only a section or several separate 
sections of the data set. You do this by using the SETL macro instruction, 
which directs the system to begin sequential retrieval at the record having a 
specific key. The processing of succeeding records is the same as for normal 
sequential processing, except that you must recognize when the last desired record 
has been processed. At this point, issue the ESETL macro to terminate 
sequential processing. You can then begin processing at another point in the 
data set. If you do not specify a SETL macro prior to retrieving the data, the 
system assumes default SETL values. (See the GET and SETL macros in Data 
Administration: Macro Instruction Reference.) 

SETL—Specify Start of Sequential Retrieval 

The SETL macro enables you to retrieve records starting at the beginning of an 
indexed sequential data set or at any point in the data set. Processing that is to 
start at a point other than the beginning can be requested in the form of a record 
key, a key class (key prefix), or an actual address of a prime data record. 

The key class concept is useful because you do not have to know the whole key 
of the first record to be processed. A key class comprises all the keys that begin 
with identical characters. The key class is defined by specifying the desired 
characters of the key class at the address specified in the lower-limit operand of 
the SETL macro and setting the remaining characters to the right of the key class 
to binary zeros. 

To use actual addresses, you must keep a record of where the records were 
written when the data set was created. The device address of the block containing 
the record just processed by a PUT-move macro instruction is available in the 
8-byte data control block field DCBLPDA. For blocked records, the address is 
the same for each record in the block. 


Normally, when a data set is created with the delete option specified, deleted 
records cannot be retrieved using the QISAM retrieval mode. When the delete 
option is not specified in the DCB, the SETL macro options function as follows: 


SETL B 

Start at the first record in the data set. 

SETL K 

Start with the record having the specified key. 

SETL KH 

Start with the record whose key is equal to or higher than the 
specified key. 

SETL KC 

Start with the first record having a key that falls into the 
specified key class. 

SETL I 

Start with the record found at the specified direct access 
address in the prime area of the data set. 


Because the DCBOPTCD field in the DCB can be changed after the data set is 
created (by respecifying the OPTCD in the DCB or DD card), it is possible to 
retrieve deleted records. In this case, SETL functions as noted above. 
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When the delete option is specified in the DCB, the SETL macro options 
function as follows: 


SETL B 


Start retrieval at the first undeleted record in the data set. 


SETL K Start retrieval at the record matching the specified key, if that 

record is not deleted. If the record is deleted, an NRF (no 
record found) indication is set in the DCBEXCD field of the 
DCB, and SYNAD is given control. 

SETL KH Start with the first undeleted record whose key is equal to or 

higher than the specified key. 

SETL KC Start with the first undeleted record having a key that falls 

into the specified key class or follows the specified key class. 


SETL I 


Start with the first undeleted record following the specified 
direct access address. 


With the delete option not specified, QISAM retrieves and handles records 
marked for deletion as nondeleted records. 

Note: Regardless of the SETL or delete option specified, the NRF condition 
will be posted in the DCBEXCD field of the DCB, and SYNAD is given control 
if the key or key class: 

• Is higher than any key or key class in the data set 

• Does not have a matching key or key class in the data set 
ESETL—End Sequential Retrieval 

The ESETL macro directs the system to stop retrieving records from an indexed 
sequential data set. A new scan limit can then be set, or processing terminated. 
An end-of-data-set indication automatically terminates retrieval. An ESETL 
macro must be executed before another SETL macro (described above) using the 
same DCB is executed. 


Note: If the previous SETL macro completed with an error, an ESETL macro 
should be executed before another SETL macro. 
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Chapter 13. Generation Data Groups 


A generation data group is a group of related cataloged data sets. The way these 
data sets are cataloged is what makes them a generation data group. Within a 
generation data group, the generations can have like or unlike DCB attributes 
and data set organizations. If the attributes and organizations of all generations 
in a group are identical, the generations can be retrieved together as a single data 
set. Each data set within a generation data group is called a generation data set. 
Generation data sets are sometimes called generations. 

There are advantages to grouping related data sets. Because the catalog 
management routines can refer to the information in a special index—called a 
generation index—in the catalog: 

• All of the data sets in the group can be referred to by a common name. 

• The operating system is able to keep the generations in chronological order. 

• Outdated or obsolete generations can be automatically deleted by the 
operating system. 

The management of a generation data group depends upon the fact that 
generation data sets have sequentially ordered names—absolute and relative 
names—that represent their age. The absolute generation name is the 
representation used by the catalog management routines in the catalog. Older 
data sets have smaller absolute numbers. The relative name is a signed integer 
used to refer to the latest (0), the next to the latest (-1), and so forth, generation. 
The relative number can also be used to catalog a new generation (+ 1). 

A generation data group base is created in an integrated catalog facility or VS AM 
catalog before the generation data sets are cataloged. A generation data group is 
represented in the integrated catalog facility or VS AM catalog by a generation 
data group base entry. The access method services DEFINE command is used to 
create the generation data group base. See Access Method Services Reference for 
information on how to define and/or catalog generation data sets in an integrated 
catalog facility or VS AM catalog. See Utilities for information on how to define 
and/or catalog generation data sets in an OS CVOL. 
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Absolute Generation and Version Numbers 


An absolute generation and version number is used to identify a specific 
generation of a generation data group. The generation and version numbers are 
in the form GxxxxVyy, where xxxx is an unsigned 4-digit decimal generation 
number (0001 through 9999) and yy is an unsigned 2-digit decimal version 
number (00 through 99). For example: 

• A.B.C.G0001V00 is generation data set 1, version 0, in generation data group 
A.B.C. 

• A.B.C.G0009V01 is generation data set 9, version 1, in generation data group 
A.B.C. 

The number of generations and versions is limited by the number of digits in the 
absolute generation name, that is, 9999 for generations and 100 for versions. 

The generation number is automatically maintained by the system. The number 
of generations kept depends on the size of the generation index. For example, if 
the size of the generation index allows ten entries, the ten latest generations may 
be maintained in the generation data group. 

The version number allows you to perform normal data set operations without 
disrupting the management of the generation data group. For example, if you 
want to update the second generation in a 3-generation group, replace generation 
2, version 0, with generation 2, version 1. Only one version is kept for each 
generation. 

A generation can be cataloged using either absolute or relative numbers. When a 
generation is cataloged, a generation and version number is placed as a low level 
entry in the generation data group. In order to catalog a version number other 
than V00, you must use an absolute generation and version number. 

A new version of a specific generation can be cataloged automatically by 
specifying the old generation number along with a new version number. For 
example, if generation A.B.C.G0005V00 is cataloged and you now create and 
catalog A.B.C.G0005V01, the new entry is cataloged in the location previously 
occupied by A.B.C.G0005V00. This process removes the old entry from the 
catalog but does not scratch the old version. To scratch the old version and 
make its space available for reallocation, a DD card, describing the data set to be 
deleted, with DISP ™ (OLD,DELETE) should be included at the time the data 
set is to be replaced by the new version. 


Relative Generation Number 

As an alternative to using absolute generation and version numbers when 
cataloging or referring to a generation, you can use a relative generation number. 
To specify a relative number, use the generation data group name followed by a 
negative integer, a positive integer, or a 0, enclosed in parentheses. For example, 
A.B.C(-l). A.B.C(+ 1), or A.B.C(O). 
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The value of the specified integer tells the operating system what generation 
number to assign to a new generation, or it tells the system the location of an 
entry representing a previously cataloged generation. 

When you use a relative generation number to catalog a generation, the operating 
system assigns an absolute generation number and a version number of V00 to 
represent that generation. The absolute generation number assigned depends on 
the number last assigned and the value of the relative generation number that you 
are now specifying. For example if, in a previous job generation, 
A.B.C.G0005Y00 was the last generation cataloged, and you specify A.B.C(+ 1), 
the generation now cataloged is assigned the number G0006V00. Though any 
positive relative generation number can be used, a number greater than 1 may 
cause absolute generation numbers to be skipped. For example, if you have a 
single step job, and the generation being cataloged is a +2, one generation 
number is skipped. However, in a multiple step job, one step may have a + 1 
and a second step a + 2, and no numbers are skipped in this case. 

Note: If you do not specify a volume in the JCL for a new generation data set, 
and the data set is not opened, that data set is not cataloged. 




Programming Considerations for Multiple Step Jobs 

One of the reasons for using generation data groups is to allow the system to 
maintain a given number of related cataloged data sets. If you attempt to delete 
or uncatalog any but the oldest of the data sets of a generation data group in a 
multiple step job, catalog management can lose orientation within the data group. 
This can cause the deletion, uncataloging, or retrieval of the wrong data set when 
referring to a specified generation. The rule is, if you delete a generation data set 
in a multiple step job, do not refer to any older generation in subsequent job 
steps. 

Also, it is recommended that, in a multiple step job, you catalog or uncatalog 
data sets using JCL instead of IEHPROGM or a user program. Because 
ALLOCATION/UNALLOCATION monitors data sets during job execution 
and is not aware of the functions performed by these programs, data set 
orientation may be lost or conflicting functions may be performed in subsequent 
job steps. 

When you use a relative generation number to refer to a generation that was 
cataloged in a previous job, the relative number has the following meaning: 

• A.B.C(O) refers to the latest existing cataloged entry. 

• A.B.C(-l) refers to the next-to-the-latest entry, and so forth. 

When cataloging is requested via JCL, all actual cataloging occurs at step 
termination, but the relative generation number remains the same throughout the 
job. Because this is so: 

• A relative number used in the JCL refers to the same generation throughout 
a job. 
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• A job step that terminates abnormally may be deferred for a later step restart. 
If the step cataloged a generation data set via JCL, you must change all 
relative generation numbers in the succeeding steps via JCL before 
resubmitting the job. 

For example, if the succeeding steps contained the relative generation numbers: 

• A.B.C( + 1), that refers to the entry cataloged in the terminated job step, or 

• A.B.C(O), that refers to the next to the latest entry, or 

• A.B.C(-l), that refers to the latest entry, prior to A.B.C(O), 

you must change them as follows before the step can be restarted: A.B.C(O), 
A.B.C(-l), A.B.C(-2), and so forth. 


Generation Data Group Naming for ISO/ANSI/FIPS Version 3 Labels 

In a Version 3 ISO/ANSI/FIPS label (LABEL = (,AL)), the generation number 
and version number are maintained separately from the file identifier. During 
label processing, the generation number and version number are removed from 
the generation data set name. The generation number is placed in the generation 
number field (file label 1 positions 36 through 39), and the version number is 
placed in its position on the same label (position 40 and 41). The file identifier 
portion of a Version 3 HDR1/EOF1/EOV1 label contains the generation data set 
name without the generation number and version number. 

For Version 3 labels, you must observe the following specifications created by the 
generation data group naming convention. 

• Data set names whose last 9 characters are of the form .GnnnnVnn (n is 0 
through 9) can only be used to specify GDG data sets. When a name ending 
in .GnnnnVnn is encountered, it is automatically processed as a GDG. The 
generation number Gnnnn and the version number Vnn are separated from 
the rest of the data set name and placed in the generation number and 
version number fields. 

• Tape data set names for GDG files are expanded from a maximum of 8 
user-specified characters to 17 user-specified characters. (The tape label file 
identifier field has space for 9 additional user-specified characters because the 
generation number and version number are no longer contained in this field.) 

• A generation number of all zeros is not valid, and will be treated as an error 
during label validation. The error appears as a “RANG” error in message 
IEC512I (IECIEUNK) during the label validation installation exit. 

• In an MVS system-created GDG name, the version number will always be 0. 
(MVS will not increase the version number by 1 for subsequent versions.) 

To obtain a version number other than 0, you must explicitly specify the 
version number (for example, A.B.C.G0004V03) when the data set is created. 
You must also explicitly specify the version number to retrieve a GDG with 
a version number other than 0. 
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• Because the generation number and version number are not contained on the 
identifier of HDR1, generations of the same GDG will have the same name. 
Therefore, an attempt to place more than one generation of a GDG on the 
same volume will result in an ISO/ANSI/FIPS standards violation in a 
system supporting Version 3, and MVS will enter the validation installation 
exit. 


Creating a New Generation 

To create a new generation data set, you must first allocate space for the 
generation, then catalog the generation. 

Allocating a Generation 

To take full advantage of the facilities of the system, the allocation can be 
patterned after a previously allocated generation in the same group. This is 
accomplished by the specification of DCB attributes for the new generation as 
described below. 

If you are using absolute generation and version numbers, DCB attributes for a 
generation can be supplied directly in the DCB parameter of the DD statement 
defining the generation to be created and cataloged. 

If you are using relative generation numbers to catalog generations, DCB 
attributes can be supplied either: (1) by creating a model DSCB on the volume 
on which the index resides (the volume containing the catalog) or (2) by referring 
to a cataloged data set for the use of its attributes. Attributes can be supplied 
before you catalog a generation, when you catalog it, or at both times, as follows: 

1. Create a model DSCB on the volume on which your index resides. You can 
provide initial DCB attributes when you create your model; however, you 
need not provide any attributes at this time. Because only the attributes in 
the data set label are used, the model data set should be allocated with 
SPACE = (TRK,0) to conserve direct access space. Initial or overriding 
attributes can be supplied when you create and catalog a generation. 1 To 
create a model DSCB, include the following DD statement in the job step 
that builds the index or in any other job step that precedes the step where 
you create and catalog your generation. 

//name DD DSNAME=datagrpname,DISP=(,KEEP),SPACE=(TRK,(0)), 
// UNIT=yyyy,VOLUME=SER=xxxxxx, 

// DCB=(applicable subparameters) 


Only one model DSCB is necessary for any number of generations. If you plan to 
use only one model, do not supply DCB attributes when you create the model. 
When you subsequently create and catalog a generation, include necessary DCB 
attributes in the DD statement referring to the generation. In this manner, any 
number of generation data groups can refer to the same model. Note that the 
catalog and model data set label are always located on a direct access volume, even 
for a magnetic tape generation data group. 
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The DSNAME is the common name by which each generation is identified; 
xxxxxx is the serial number of the volume containing the catalog. If no DCB 
subparameters are wanted initially, you need not code the DCB parameter. 

2. You do not need to create a model DSCB if you can refer to a cataloged data 
set whose attributes are identical to those you desire or to an existing model 
DSCB for which you can supply overriding attributes. To refer to a 
cataloged data set for the use of its attributes, specify DCB = (dsname) on the 
DD statement that creates and catalogs your generation. To refer to an 
existing model, specify DCB = (modeldscbname, your attributes) on the DD 
statement that creates and catalogs your generation. 

Passing a Generation 


A new generation may be passed when created. That generation may then be 
cataloged in a succeeding job step or deleted at the end of the job as in normal 
disposition processing when DISP = (,PASS) is specified on the DD statement. 

However, after a generation has been created with DISP = (NEW,PASS) specified 
on the DD statement, another new generation for that data group must not be 
cataloged until the passed version has been deleted or cataloged. To do so would 
cause the wrong generation to be used when referencing the passed generation 
data set. If that data set was later cataloged, a bad generation would be cataloged 
and a good one lost. 

For example, if A.B.C( + 1) was created with DISP= (NEW,PASS) specified on 

the DD statement, then A.B.C.( + 2) must not be created with 

DISP = (NEW,CATLG) until A.B.C(+ 1) has been cataloged or deleted. 

By using the proper JCL, the advantages to this support are: 

• JCL will not have to be changed in order to rerun the job. 

• The lowest generation version will not be deleted from the index until a valid 
version is cataloged. 

Creating an ISAM Data Set as Part of a Generation Data Group 

To create an indexed-sequential data set as part of a generation data group, you 
must: (1) create the indexed-sequential data set separately from the generation 
group and (2) use IEHPROGM to put the indexed-sequential data set into the 
generation group. 

In an integrated catalog facility and VSAM catalogs, use access method services 
commands to catalog the data set. In an OS CVOL, use the RENAME function 
to rename the data set. Then use the CATLG function to catalog the data set. 
For instance, if MASTER is the name of the generation data group, and 
GggggVw is the absolute generation name, you would code the following: 

RENAME DSNAME=ISAM,VOL=3380=SCRTCH,NEWNAME=MASTER.GggggVw 
CATLG DSNAME=MASTER. GggggVw,V0L=3380=SCRTCH 
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Retrieving a Generation 


A generation may be retrieved through the use of job control language 
procedures. Any operation that can be applied to a nongeneration data set can 
be applied to a generation. For example, a generation can be updated and 
reentered in the catalog, or it can be copied, printed, punched, or used in the 
creation of new generation or nongeneration data sets. 

You can retrieve a generation by using either relative generation numbers or 
absolute generation and version numbers. 

Because two or more jobs can compete for the same resource, generation data 
groups should be updated with care, as follows: 

• No two jobs running concurrently should refer to the same generation data 
group. As a partial safeguard against this situation, use absolute generation 
and version numbers when cataloging or retrieving a generation in a 
multiprogramming environment. If you use relative numbers, a job running 
concurrently may update the generation data group index, perhaps cataloging 
a new generation which you will then retrieve in place of the one you 
wanted. 

• Even when using absolute generation and version numbers, a job running 
concurrently might catalog a new version of a generation or perhaps delete 
the generation you wanted to retrieve. For this reason, some degree of 
control should be maintained over the execution of job steps referring to 
generation data groups. 


Building a Generation Data Group Index 

A generation data group is managed via the information found in a generation 
index. (Note that an alias name cannot be assigned to the highest level of a 
generation index.) The BLDG function of IEHPROGM builds the index. The 
BLDG function also indicates how older or obsolete generations are to be 
handled when the index is full. For example, when the index is full, you may 
want to empty it, scratch existing generations, and begin cataloging a new series 
of generations. 

After the index is built, a generation can be cataloged by its generation data 
group name and either an absolute generation and version number or a relative 
generation number. 

Examples of how to build a generation data group index are found in Utilities , 
under IEHPROGM. 


/ 
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Chapter 14. I/O Device Control Macros 


The operating system provides you with several macros for controlling 
input/output devices. Each is, to varying degrees, device dependent. Therefore, 
you must exercise care if you want to achieve device independence. 

When you use the queued access technique, only unit record equipment can be 
controlled directly. When using the basic access technique, limited device 
independence can be achieved between magnetic tape and direct access devices. 
You must check all read or write operations before issuing a device control 
macro. 


CNTRL—Control an I/O Device 

The CNTRL macro performs these device-dependent control functions: 

• Card reader stacker selection (SS) 

• Printer line spacing (SP) 

• Printer carriage control (SK) 

• Magnetic tape backspace (BSR) over a specified number of blocks 

• Magnetic tape backspace (BSM) past a tapemark and forward space over the 
tapemark 

• Magnetic tape forward space (FSR) over a specified number of blocks 

• Magnetic tape forward space (FSM) past a tapemark and a backspace over 

the tapemark 

Backspacing moves the tape toward the load point; forward spacing moves the 
tape away from the load point. 

Note that the CNTRL macro cannot be used with an input data set containing 
variable-length records on the card reader. 

If you specify OPTCD- H in the DCB parameter field of the DD statement, you 
can use the CNTRL macro to position DOS tapes that contain embedded DOS 
checkpoint records. The CNTRL macro cannot be used to backspace DOS 
7-track tapes that are written in data convert mode and contain embedded 
checkpoint records. 
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PRTOV— Test for Printer Overflow 


I ■■ 

The PRTOV macro tests for channel 9 or 12 of the printer carriage control tape 
or the forms control buffer (FCB). An overflow condition causes either an 
automatic skip to channel 1 or, if specified, transfer of control to your routine for 
overflow processing. If you specify an overflow exit routine, set DCBIFLGS to 
X f 00 f before issuing another PRTOV. 

If the data set specified in the DCB is not for a printer, no action is taken. 

SETPRT-Printer Setup 

The SETPRT macro instruction is used to control how information is printed. 

It is used with the 3800 Printing Subsystem and with various other universal 
character set (UCS) printers. 

For the IBM 3800 Printing Subsystem, the SETPRT macro instruction is used to 
initially set or dynamically change the printer control information. For additional 
information on how to use the SETPRT macro with the 3800 printer, see IBM 
3800 Printing Subsystem Programmer s Guide. 

For printers that have a universal character set (UCS) buffer and optionally, a 

forms control buffer (FCB), the SETPRT macro instruction is used to specify the 

UCS and/or FCB images to be used. Note that universal character sets for the 

various printers are not compatible. The three formats of FCB images (the FCB % 

image for the 3800 Printing Subsystem, the 4248 format FCB and the 3211 V y 

format FCB) are incompatible. The 3211 format FCB is used by the 3203, 3211, 

4248, 3262 Model 5, and 4245 printers. 

IBM-supplied UCS images, UCS image tables, FCB images, and character 
arrangement table modules are included in the SYS1.IMAGELIB at system 
generation time. For 1403, 3203, 3211, 3262 Model 5, 4245, and 4248 printers, 
user-defined character sets can be added to SYS1.IMAGELIB. For a description 
of how images are added to SYS1.IMAGELIB and how band names/aliases are 
added to image tables, see System-Data Administration. For the 3800, 
user-defined character arrangement table modules, FCB modules, GRAPHIC 
modules, copy modification modules, and library character sets can be added to 
SYS1.IMAGELIB as described in Utilities. For information on building a 4248 
format FCB (which can also be used for the IBM 3262 Model 5 printer), see 
Utilities. 

The FCB contents can be selected from the system library (or an alternate library 
if you are using a 3800), or defined in your program through the exit list of the 
DCB macro instruction, as discussed under “Exit List (EXLST)” on page 80. 

For a non-3800 printer, the specified UCS or FCB image should be found in one 
of the following: 

• SYS1.IMAGELIB 

• Image table (UCS Image only) 

• DCB exit list for an FCB 
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If the image is not found, the operator is asked to specify an alternate image 
name or cancel the request. 

For a printer that has no carriage control tape, you can use the SETPRT macro 
instruction to select the FCB, to request operator verification of the contents of 
the buffer, or to allow the operator to align the paper in the printer. 

BSP—Backspace a Magnetic Tape or Direct Access Volume 

The BSP macro backspaces one block on the magnetic tape or direct access 
volume being processed. The block can then be reread or rewritten. An attempt 
to rewrite the block destroys the contents of the remainder of the tape or track. 

The direction of movement is toward the load point or beginning of the extent. 
You may not use the BSP macro if the track overflow option was specified or if 
the CNTRL, NOTE, or POINT macro instruction is used. The BSP macro 
should be used only when other device control macros could not be used for 
backspacing. 

Any attempt to backspace across a file mark will result in a return code of 
X T 04 1 in register 15 and your tape or direct access volume will be positioned 
after the file mark. This means you cannot issue a successful backspace 
command after your EODAD routine is entered unless you first reposition the 
tape or direct access volume into your data set. (CLOSE TYPE = T can position 
you at the end of your data set.) 

You can use the BSP macro to backspace DOS tapes containing embedded DOS 
checkpoint records. If you use this means of backspacing, you must test for and 
bypass the embedded checkpoint records. You cannot use the BSP macro for 
DOS 7-track tapes written in translate mode. 


NOTE—Return the Relative Address of a Block 

The NOTE macro requests the relative address of the block just read or written. 
In a multi volume data set, the address is relative to the beginning of the data set 
on the volume currently being processed. 

For magnetic tape, the address is in the form of a 4-byte relative block address. If 
TYPE= REL is specified or defaults, the address provided by the operating 
system is returned in register 1. If TYPE = ABS is specified, the physical block 
identifier of a data block on tape is returned in register 0. The relative block 
address or the block identifier can later be used as a search argument for the 
POINT macro. 

For a direct access device, the address is in the form of a 4-byte relative track 
address. The address provided by the operating system is returned in register 1, 
and the amount of unused space available on the track of the direct access device 
is returned in register 0. 
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POINT—Position to a Block 


The POINT macro causes repositioning of a magnetic tape or direct access 
volume to a specified block. The next read or write operation begins at this 
block. In a multivolume data set, you must ensure that the volume referred to is 
the volume currently being processed. For disk, if a write operation follows the 
POINT macro, all of the track following the write operation is erased, unless the 
data set is opened for UPDAT. POINT is not meant to be used before a 
WRITE macro when a data set is opened for UPDAT. If you specify 
OPTCD = H in the DCB parameter field of the DD statement, you can use the 
POINT macro to position DOS tapes that contain embedded checkpoint records. 
The POINT macro cannot be used to backspace DOS 7-track tapes that are 
written in data convert mode and contain embedded checkpoint records. 

If you specify TYPE = ABS, you can use the physical block identifier as a search 
argument to locate a data block on tape. The identifier may be provided from 
the output of a prior execution of the NOTE macro. 

When using the POINT macro for a direct access device that is opened for 
OUTPUT, OUTIN, or INOUT, and the record format is not standard, the 
number of blocks per track may vary slightly. 

SYNCDEV—Control*Data Synchronization 

The SYNCDEV macro controls data synchronization for devices supporting 
buffered write mode. Data still in the buffer may not yet reside on the final 
recording medium. This is referred to as data that is not synchronized. You can 
either 

• Request information regarding synchronization. 

• Demand that synchronization occur based on a specified number of data 
blocks that are allowed to be buffered. If zero is specified, synchronization 
will always occur. 

When SYNCDEV completes successfully (return code 0), a value will be returned 
that indicates the number of data blocks remaining in the control unit buffer. 
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Chapter 15. Protecting Data 


Control of confidential data in a data set is provided through password 
protection. You can prevent unauthorized access to payroll data, sales forecast 
data, and all other data sets that require special security attention. An individual 
can use a security-protected data set only after supplying a predefined password. 


Password Protection for Non-VS AM Data Sets 

Password protection as described here applies to non-VSAM data sets only. For 
information on password protection for VS AM data sets, see Access Method 
Services Reference. 

In addition to the usual label protection that prevents opening of a data set 
without the correct data set name, the operating system provides data set security 
options that prevent unauthorized access to confidential data. Two levels of 
protection options are available. You specify these options in the LABEL field 
of a DD statement with the parameter PASSWORD or NOPWREAD. 

• Password protection (specified by the PASSWORD parameter) makes a data 
set unavailable for all types of processing until a correct password is entered 
by the system operator, or for a TSO job by the TSO user. 

• No-password-read protection (specified by the NOPWREAD parameter) 
makes a data set available for input without a password, but requires that the 
password be entered for output or delete operations. 

If an incorrect password is entered twice when a job is being requested by the 
open or EOV routine, the job is terminated by the system. For a SCRATCH or 
RENAME request, a return code is given. 

You can request password protection when you create the data set, by using the 
LABEL field of the DD statement in your JCL. The system sets the data set 
security byte either in the standard header label 1 as shown in Magnetic Tape 
Labels and File Structure or in the identifier data set control block (DSCB) as 
shown in Debugging Handbook. After you have requested security protection for 
magnetic tapes, you cannot remove it with JCL unless you re-create the data set 
and scratch the protected data set. 

In addition to requesting password protection in your JCL, you must enter at 
least one record for each protected data set in a data set named PASSWORD, 
which must be created on the system-residence volume. You should also request 
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password protection for the PASSWORD data set itself to prevent both reading 
and writing without knowledge of the password. 

For a data set on a direct access device, you can place the data set under 
protection when you enter its password in the PASSWORD data set. You can 
use the PROTECT macro or the IEHPROGM utility program to add, change, 
or delete an entry in the PASSWORD data set; with either of these methods, the 
system updates the DSCB of the data set to reflect its protected status. This 
provision eliminates the need for you to use JCL whenever you add, change, or 
remove security protection for a data set on a direct access device. System-Data 
Administration describes how to maintain the PASSWORD data set, including 
the PROTECT macro instruction; Utilities describes the IEHPROGM utility 
program. 


RACK Protection for Non-VSAM Data Sets 

Resource Access Control Facility (RACF) protection as described here applies to 
non-VSAM data sets, tape data sets, and tape volumes. For information on 
RACF protection for VSAM data sets, see VS AM Administration Guide . For 
detailed information on RACF protection for data sets, see RACF General 
Information Manual and RACF Security Administrator's Guide. 

RACF is an IBM licensed program that provides access control by identifying 
and verifying users and authorizing access to DASD 

You may define a data set to RACF automatically or explicitly. The automatic 
definition occurs when space is allocated for the DASD data set, if the user has 
the automatic data set protection attribute or if PROTECT = YES is coded on 
the DD statement. The explicit definition of a data set to RACF is by use of the 
RACF command language. A tape volume is defined to RACF explicitly by use 
of the RACF command language or automatically. All data sets on a tape 
volume are RACF protected if the volume is RACF protected. 

Five levels of access authority are possible in a RACF-defined data set or tape 
volume. 

ALTER 

You have total control over the data set. If you define the data set or tape 
volume to RACF, you have ALTER access authority. With ALTER 
authority, you can read and write the data set or tape volume, rename the 
data set, and scratch the data set, and you may authorize other users access 
to the tape volume or data set. 

CONTROL 

For non-VSAM data sets, CONTROL authority is equivalent to UPDATE 
authority. 

UPDATE 

You are authorized to open the data set or tape volume for OUTPUT and 
all other open options. 
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READ 

You are authorized to open the data set or tape volume for INPUT only. 

NONE 

You are not authorized to open the data set or tape volume. 

If a data set is defined to RACF and is password protected, access to the data set 
is authorized only through RACF authorization checking. If a tape volume is 
defined to RACF and the data set(s) on the tape volume is password protected, 
access to any of the data sets is authorized only through RACF authorization 
checking of the volume. Data set password protection is bypassed. 

To protect multivolume non-VSAM DASD and tape data sets, you must define 
each volume of the data set to RACF as part of the same volume set. When a 
RACF-protected data set is opened for output and extended to a new volume, 
the new volume is automatically defined to RACF as part of the same volume 
set. When a multi volume physical-sequential data set is opened for output either 
each subsequent volume must be RACF protected as part of the same volume 
set, or the data set must not yet exist on the volume, multivolume tape data set 
is opened for output, either each subsequent volume must be RACF protected as 
part of the same volume set, or the tape volume must not yet be defined to 
RACF. If the first volume opened is not RACF protected, no subsequent 
volume may be RACF protected. If a multivolume data set is opened for input 
(or a nonphysical-sequential data set is opened for output), no such consistency 
check is performed when subsequent volumes are accessed. 

ISO/ANSI/FIPS Version 3 installation exits that execute under RACF will 
receive control during ANSI volume label processing. Control will go to the 
RACHECK preprocessing and postprocessing installation exits. The same 
IECIEPRM exit parameter list passed to ANSI installation exits will be passed 
to the RACF installation exits if the accessibility code is any alphabetic character 
from A through Z. For more information, see Magnetic Tape Labels and File 
Structure . 
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Appendix A. Direct Access Labels 


Only standard label formats are used on direct access volumes. Volume, data set, 
and optional user labels are used (see Figure 65). In the case of direct access 
volumes, the data set label is the data set control block (DSCB). 


Tracks 


Figure 



Volume-Label Group 

The volume-label group immediately follows the first two initial program loading 
(IPL) records on track 0 of cylinder 0 of the volume. It consists of the initial 
volume label at record 3 plus a maximum of seven additional volume labels. The 
initial volume label identifies a volume and its owner, and is used to verify that 
the correct volume is mounted. It can also be used to prevent use of the volume 
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by unauthorized programs. The additional labels can be processed by an 
installation routine that is incorporated into the system. 

The format of the direct access volume label group is shown in Figure 66. 

(As many as Seven Additional Volume Labels) 
80-Byte Physical Record 

Volume Label Identifier (VOL) 

Volume Label Number (1) 

Volume Serial Number 

Volume Security 

VTOC Pointer 

Reserved (Blank) 

Owner Identification 

Blank 

Figure 66. Initial Volume Label 



Initial Volume Label Format 

The 80-byte initial volume label is preceded by a 4-byte key containing VOL1. 

Volume Label Identifier (VOL): Field 1 identifies a volume label. 

Volume Label Number (I): Field 2 identifies the relative position of the volume 
label in a volume label group. It must be written as XTT. 

The operating system identifies an initial volume label when, in reading the initial 
record, it finds that the first 4 characters of the record are VOL 1. 

Volume Serial Number: Field 3 contains a unique identification code assigned 
when the volume enters the system. You can place the code on the external 
surface of the volume for visual identification. The code is normally numeric 
(000001 through 999999), but may be any 1 to 6 alphameric or national (#, $, @) 
characters, or a hyphen (X'60'). If this field is less than 6 characters, it is padded 
on the right with blanks. 

Volume Security: Field 4 is reserved for use by installations that want to provide 
security for volumes. Make this field a X'CO' unless you have your own security 
processing routines. 
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VTOC Pointer: Field 5 of direct access volume label 1 contains the address of 
the VTOC in the form of CCHHR. 

Reserved: Field 6 is reserved for possible future use. Leave it blank. 

Owner Name and Address Code: Field 7 contains a unique identification of the 
owner of the volume. 

All the bytes in Field 8 are left blank. 


Data Set Control Block (DSCB) 

The system automatically constructs a DSCB when space is requested for a data 
set on a direct access volume. Each data set on a direct access volume has one or 
more DSCBs to describe its characteristics. The DSCB appears in the VTOC 
and, in addition to space allocation and other control information, contains 
operating system data, device-dependent information, and data set characteristics. 
There are seven kinds of DSCBs, each with a different purpose and a different 
format number. For an explanation of Format-1 through Format-6 DSCBs, see 
System-Data Administration. Format 0 DSCBs are used to indicate empty space 
in the VTOC. 


User Label Groups 

User header and trailer label groups can be included with data sets of physically 
sequential or direct organization. The labels in each group have the format 
shown in Figure 67. 



80—Byte Physical Record (Maximum of 8) 

Label Identifier (UHL if Header, UTL if Trailer) 
Label Number (1 - 8) 


User-Specified 


Figure 67. User Header and Trailer Labels 


Each group can include as many as eight labels, but the space required for both 
groups must not be more than 1 track on a direct access device. The current 
minimum track size allows a maximum of eight labels, including both header and 
trailer labels. Consequently, a program becomes device dependent (among direct 
access devices) when it creates more than eight labels. 
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If user labels are specified in the DD statement (LABEL = SUL), an additional 
track is normally allocated when the data set is created. No additional track is 
allocated when specific tracks are requested (SPACE = (ABSTR,...)), or when 
tracks allocated to another data set are requested (SUBALLOC = ...). In either 
case, labels are written on the first track that is allocated. 

User Header Label Group: The operating system writes these labels as directed 
by the processing program recording the data set. The first 4 characters of the 
user header label must be UHL1,..., UHL8; you can specify the remaining 76 
characters. When the data set is read, the operating system makes the user header 
labels available to the problem program for processing. 

User Trailer Label Group: These labels are recorded (and processed) as explained 
in the preceding text for user header labels, except that the first 4 characters must 
be UTL1,...,UTL8. 

User Header and Trailer Label Format 

Label Identifier: Field 1 indicates the kind of user header label. UHL indicates a 
user header label; UTL indicates a user trailer label. 

Label Number: Field 2 identifies the relative position (1 to 8) of the label within 
the user label group. 

User-Specified: Field 3 (76 bytes). 
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Appendix B. Control Characters 


As an optional feature, each logical record, in any record format, may include a 
control character. This control character is recognized and processed if a data set 
is being written to a printer or punch. 

For format-F and format-U records, this character is the first byte of the logical 
record. 

For format-V records, it must be the fifth byte of the logical record, immediately 
following the record descriptor word. 

Two options are available. If either option is specified in the DCB, the character 
must appear in every record and other line spacing or stacker selection options 
also specified in the DCB are ignored. 


Machine Code 


You can specify in the DCB that the machine code control character has been 
placed in each logical record. If the record is to be written, the appropriate byte 
must contain the command code bit configuration specifying both the write and 
the desired carriage or stacker select operation. 

The machine code control characters for a printer are: 


Print—Then 

Act 

Action 

Act Immediately 
without Printing 

x'or 

Print only (no space) 


xw 

Space 1 line 

XW 

xtt 

Space 2 lines 

XT 3' 

XT 9' 

Space 3 lines 

XTB' 

X'89' 

Skip to channel 1 

XW 

X'91' 

Skip to channel 2 

X'93' 

X'99' 

Skip to channel 3 

XW 
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Print—Then 

Act 

Action 

Act Immediately 
without Printing 

X'Al' 

Skip to channel 4 

X'A3' 

X'A9' 

Skip to channel 5 

X'AB' 

XBr 

Skip to channel 6 

X'B3' 

X'B9' 

Skip to channel 7 

XBB' 

x'cr 

Skip to channel 8 

XC3' 

X'C9' 

Skip to channel 9 

XCB' 

X DT 

Skip to channel 10 

X'D3' 

X D9' 

Skip to channel 11 

X'DB' 

X'ET 

Skip to channel 12 

XE3' 


The machine code control characters for a card read punch device are as follows: 
Control Code Action 

Select stacker 1 
Select stacker 2 


X'01' 

X'4T 

X'5A' : 


X'8T 


Change from line 
mode to page mode 

Select stacker 3 


! The 3800 Model 3 all-point-addressable mode uses this code to change from 
comparability to page mode. 

Other command codes for specific devices are contained in publications 
describing the control units and devices. 
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Extended American National Standards Institute Code 

In place of machine code, you can specify control characters defined by the 
American National Standards Institute (ANSI). Whenever IBM publications 
refer to ANSI control characters, they are coded as follows: 


Code 

Action before Printing a Line 

b 

Space one line (blank code) 

0 

Space two lines 

- 

Space three lines 


Suppress space 

1 

Skip to channel 1 

2 

Skip to channel 2 

3 

Skip to channel 3 

4 

Skip to channel 4 

5 

Skip to channel 5 

6 

Skip to channel 6 

7 

Skip to channel 7 

8 

Skip to channel 8 

9 

Skip to channel 9 

A 

Skip to channel 10 

B 

Skip to channel 11 

C 

Skip to channel 12 

Code 

Action after Punching a Card 

V 

Select punch pocket 1 

W 

Select punch pocket 2 

X'5A'> 

Change from line to page mode 


l The 3800 Model 3 all-point-addressable mode uses this code 

These control characters include those defined by ANSI FORTRAN. If any 
other character is specified, it is interpreted as ‘b’ or a V, depending on whether it 
is for a printer or a punch; no error indication is returned. 
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ly 


Appendix C. Allocating Space on Direct Access Volumes 


When direct access storage space is required for a data set, you can specify the 
amount of space needed, the device type, and, optionally, the volume. The 
operating system selects the device and allocates the space accordingly. 

When the data set is to be stored on a direct access volume, you must supply, in 
the DD statement, control information designating the amount of space to be 
allocated and how it is to be allocated. 

The amount of space required can be specified in blocks, tracks, or cylinders. If 
you want to maintain device independence, specify your space requirements in 
blocks. If your request is in tracks or cylinders, you must be aware of such 
device considerations as cylinder and track capacity. 

Cylinder allocation allows faster input/output of sequential data sets than does 
track or block allocation unless your device supports Define Extent or Locate 
Record. 

Allocation by Blocks: When the amount of space required is expressed in blocks, 
you must specify the number and average length of the blocks within the data set, 
as in this example: 

// DD SPACE=(300,(5000,100)), ... 

300 = average block length in bytes 
5000 = primary quantity (number of blocks) 

100 = secondary quantity, to be allocated if the primary 
quantity is not enough (in blocks) 

From this information, the operating system estimates and allocates the number 
of tracks required. Space is always in complete tracks. You may also request 
that the space allocated for a specific number of blocks begin and end on cylinder 
boundaries. 

You must be certain that both the quantity and the increment are large enough 
to contain the largest block to be written. Otherwise, all the space requested is 
allocated but erased as the system tries to find a space large enough for the 
record. 

Allocation by Tracks or Cylinders: The amount of space required can be 
expressed in tracks or cylinders, as in these examples: 

// DD SPACE=(TRK,(100,5)), . . . 

// DD SPACE=(CYL,(3,1)), . . . 


Appendix C. Allocating Space on Direct Access Volumes 217 



Allocation by Absolute Address: If the data set contains location-dependent 
information in the form of an absolute track address (MBBCCHHR), space 
should be requested about the number of tracks and the beginning address, as in 
this example: 

// DD SPACE=(ABSTR,(500,15)),UNIT=3380, . . . 

where 500 tracks axe required, beginning at relative track 15, which is cylinder 1, 
track 0. 

Allocation of Mass Storage System (MSS) Virtual Volumes: When the data set 
is to be stored on an MSS virtual volume, a volume group (MSVGP) parameter 
may be specified instead of using the SPACE parameter on the DD card. Before 
the MSVGP parameter can be used, the volume group must be identified to MSS 
by the utility program IDCAMS. 

Allocation of MSS virtual volume space should be in multiples of cylinders, with 
secondary allocation a multiple of the primary to ensure maximum space usage 
and minimum fragmentation. 

Additional Space Allocation Options: The DD statement provides you with 
much flexibility in specifying space requirements. The options are described in 
detail in JCL. 

Estimating Space Requirements 

To determine how much space your data set requires, you must consider these 
variables for the device type: 

• Track capacity 

• Tracks per cylinder 

• Cylinders per volume 

• Data length (block size) 

• Key length 

• Device overhead 

Figure 68 on page 219 lists the physical characteristics of several direct access 
storage devices. 
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Device 

Volume 

Type 

Maximum 
Block size 
per Track 1 

Tracks per 
Cylinder 

Number 

of 

Cylinders 2 

Total 

Capacity 1 , 2 

2305-2 

Disk 

14660 

8 

96 

11258880 

3330/3333 3 
(Model 1) 

Disk 

13030 

19 

404 

100018280 

3330/3333 
(Model 11) 

Disk 

13030 

19 

808 

200036560 

3340/3344 4 

Disk 

8368 

12 

696 

(70 megabytes) 
348 

(35 megabytes) 

69889536 

34944768 

3350 

Disk 

19069 

30 

555 

317498850 

3375 

Disk 

32760 s 

12 

959 

409868928 

3380 

Disk 

32760 s 

15 

885 

630243900 

3380 

(Models 

AD4 and BD4) 

Disk 

32760 s 

15 

885 

630243900 

3380 

(Models 

AE4 and BE4) 

Disk 

32760 s 

15 

1770 

1260487800 


1 Capacity indicated in bytes (when RO is used by the IBM programming system). 

2 Excluding alternate cylinders. 

3 The Mass Storage System (MSS) virtual volumes assume the characteristics of the 3330/3333, Model 1. 

4 The 3344 is functionally equivalent to the 3340 Model 70. 

5 The largest record that can be written on a track is 35616 bytes for the 3375 and 47476 bytes for all 
3380 models. However, for these devices, the largest block size supported by the standard access 
methods is 32760 bytes. 

Figure 68. Direct Access Storage Device Capacities 


The term device overhead refers to the space required on each track for hardware 
data, that is, address markers, count areas, gaps between records, record 0, and so 
forth. Device overhead varies with each device and depends also on whether the 
blocks are written with keys. To compute the actual space required for each 
block, including device overhead, you can use the formulas in Figure 69 on 
page 220. Note that any fraction of a byte must be ignored in any operation of 
the calculation. For example, if the formula gives 15.644 bytes, you must allocate 
15 bytes. 
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Note: You may choose to use the TRKCALC macro to perform track capacity 

calculations. See System — Data Administration for further information on v y 

TRKCALC. 


Bytes Required by Each Data Block ^ 


Device 

Track 

Capacity 

Blocks with Keys 

Blocks without Keys 

2305-2 

14858 2 

289+KL+DL 

198+ DL 

3330/3333 3 
(Model 1 or 

11) 

13165 

191 + KL+DL 

135+DL 

3340/3344 

8535 2 

242 + KL + DL 

167 +DL 

3350 

19254 2 

267+KL+DL 

185 +DL 

3375 

36000 

224+ ((KL+ 191)/32)(32) + 
((DL+ 191)/32)(32) 

224+((DL+ 191)/32)(32) 

3380 

(all models) 

( 

47968 

256 + ((KL + 267)/32) 

(32) + ((DL + 267)/32)(32) 

256+((DL + 267)/32)(32) 

3380 Models 
AD4 and BD4 

47968 

256+ ((KL+ 267)/32) 

(32) + ((DL + 267)/32)(32) 

256+((DL + 267)/32)(32) 

3380 Models 
AE4 and BE4 

47968 

256 + ((KL + 267)/32) 

(32) + ((DL + 267)/32)(32) 

256+((DL + 267)/32)(32) 


Figure 69. Direct Access Device Overhead Formulas 

Legend: 

DL is data length. 

KL is key length. 

Notes: 

1 Use modulo-32 arithmetic when calculating key length and data length terms 
in your equations. Compute these terms first, then round up to the nearest 
increment of 32 bytes before completing the equation. 

2 This value is different from the maximum block size per track because the 
formula for the last block on the track includes an overhead for this device. 

3 The. Mass Storage System (MSS) virtual volumes assumes the characteristics 
of the 3330/3333, Model 1. 

The formulas can be combined in the following way: 

If you intend to specify your space requirements in tracks (TRK) or cylinders 

(CYL), your estimate should be made as shown above. If you request absolute 

tracks (ABSTR), remember that you cannot allocate track 0, cylinder 0. The 
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amount of space required for the VTOC will reduce the space available on the 
rest of the volume. 

If you specify your space requirements in average block length, the system 
performs the computations for you. 

Because a sequential data set and a direct data set are created in the same way, 
the estimate and specification of space requirements are identical. If you use the 
WRITE SZ macro, your secondary allocation for a direct data set should be at 
least 2 tracks. Space allocation for a partitioned data set requires that you also 
consider the space used for the directory. Similarly, allocation for an indexed 
sequential data set requires that you consider the space needed for the prime area, 
index areas, and overflow areas. 
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Appendix D. ISO/ANSI/FIPS Record Control Word and Segment 
Control Word 


Translation of ISO/ANSI/FIPS Record Control Word 

The ISO/ANSI/FIPS record control word (RCW) is expressed in ISCII/ASCII 
characters and is 4 bytes long (see Figure 70). Note that the RCW is different 
from the code in the IBM record descriptor word (RDW). The RDW, expressed 
in binary, is the internal data management equivalent of the ISO/ANSI/FIPS 
RCW. 


D/DB RDW 


ISO/ANSI RCW 




Figure 70. Translation of ISO/ANSI/FIPS Record Control Word to D/DB Record Descriptor Word 
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Translation of ISO/ANSI/FIPS Segment Control Word 


The ISO/ANSI/FIPS segment control word (SCW) is expressed in ISCII/ASCII 
characters and is 5 bytes in length. (See Figure 71.) Note that the SCW is 
different from the code in the IBM segment descriptor word (SDW). The SDW 
is the internal data management equivalent of the ISO/ANSI/FIPS SCW. Only 4 
bytes are used by data management, but the user buffer area must accommodate 
an extra byte to allow for translation from the ISO/ANSI/FIPS SCW. The SDW 
is expressed in binary. 


DS/DBS SDW 


ISO/ANSI SCW 


Spanning Indicator 


Length in 
ISCII/ASCII 
Numeric 
Characters 


1 C values for SDW (2 low order 

bits) 

00 = only segment of record 
01 = first segment of record 
11 = intermediate segment of record 
10 = last segment of record 

2 S values for SCW (ASCII characters) 

0 = only segment of record 

1 = first segment of record 

2 = intermediate segment of record 

3 = last segment of record 

Figure 71. Translation of ISO/ANSI/FIPS Segment Control Word to DS/DBS Segment Descriptor Word 


Reserved 

Output Tr; 
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Glossary of Terms and Abbreviations 


The following terms are defined as they are used in this 
book. If you do not find the term you are looking for, 
see the index or the IBM Vocabulary for Data 
Processing , Telecommunications , and Office Systems , 
GC20T699. 

A. ANSI control code (value of RECFM) 

ABE. abnormal end (value of EROPT) 

ABEND, abnormal end (macro instruction) 

ABSTR. absolute track (value of SPACE) 

ACC. accept erroneous block (value of EROPT) 

AFF. affinity (channel separation parameter of DD 
statement or unit affinity value of UNIT) 

AL. American National Standard Labels 

ANSI. American National Standards Institute 

ASCII. American National Standard Code for 
Information Interchange 

AUL. American National Standard user labels (value 
of LABEL) 

B. blocked records (value of RECFM) 

BCDIC. binary coded decimal interchange code 
BDAM. basic direct access method 

BDW. block descriptor word 

BFALN. buffer alignment (operand of DCB) 

BFTEK. buffer technique (operand of DCB) 

BIS AM. basic indexed sequential access method 
BLDL. build list (macro instruction) 

BLKSIZE. blocksize (operand of DCB) 

BPAM. basic partitioned access method 


BPI. bytes per inch 

BSAM. basic sequential access method 

BSM. backspace past tapemark and forward space 
over tapemark (operand of CNTRL) 

BSP. backspace one block (macro instruction) 

BSR. backspace over a specified number of blocks 
(records) (operand of CNTRL) 

BUFCB. buffer pool control block (operand of DCB) 

BUFL. buffer length (operand of DCB) 

BUFNO. buffer number (operand of DCB) 

BUFOFF. buffer offset (length of ASCII block prefix 
by which the buffer is offset; operand of DCB) 

CCW. channel command word 

CONTIG. contiguous space allocation (value of 
SPACE) 

CNTRL. control (macro instruction) 

CSW. channel status word 

CYLOFL. number of tracks for cylinder overflow 
records (operand of DCB) 

D. format-D (ISCII/ASCII variable-length) records 
(value of RECFM) 

DA. direct access (value of DEVD or DSORG) 

DAU. direct access unmovable data set (value of 
DSORG) 

DB. ISCII/ASCII variable-length, blocked records 
(value of RECFM) 

DBS. ISCII/ASCII variable-length, blocked spanned 
records (value of RECFM) 

DCB. data control block (control block name or macro 
instruction or parameter on DD statement) 
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DCBD. data control block dummy section (macro 
instruction) 

DD. data definition(statement) 

DEB. data extent block 

DECB. data event control block 

DEN. magnetic tape density (operand of DCB) 

DEVD. device-dependent (operand of DCB) 

DISP. data set disposition (parameter of DD 
statement) 

DS. ISCII/ASCII variable-length, spanned records 
(value of RECFM) 

DSCB. data set control block 

DSORG. data set organization (operand of DCB) 

EBCDIC, extended binary-coded decimal interchange 
code 

EODAD. end-of-data set exit routine address (operand 
of DCB) 

EOF. end-of-file 

EOV. end-of-volume 

EROPT. error options (operand of DCB) 

ESETL. end sequential retrieval (QISAM macro 
instruction) 

EXCP. execute channel program (macro instruction) 
EXLST. exit list (operand of DCB) 

F. fixed-length records (value of RECFM) 

FB. fixed-length, blocked records (value of RECFM) 

FBS. fixed-length, blocked, standard records (value of 
RECFM) 

FBT. fixed-length, blocked records with track overflow 
option (value of RECFM) 

FCB. forms control buffer 

FEOV. force end-of-volume (macro instruction) 

FIPS. Federal Information Processing Standard 

FS. fixed-length, standard records (value of RECFM) 


FSM. forward space past tapemark and backspace 
over tapemark (operand of CNTRL) 

FSR. forward space over a specified number of blocks 
(records) (operand of CNTRL) 

GCR. group coded recording(tape recording mode) 

GL. GET macro, locate mode (value of MACRF) 

GM. GET macro, move mode (value of MACRF) 

H. DOS tapes with embedded checkpoint records 
(parameter of OPTCD) 

HA. home address 

ICF catalog, integrated catalog facility catalog 

INOUT. input then output (operand of OPEN) 

I/O. input/output 

I OB. input/output block 

IPL. initial program load 

IRG. interrecord gap 

IS. indexed sequential (value of DSORG) 

ISAM, indexed sequential access method 

ISCII. International Standard Code for Information 
Interchange 

ISO. International Organization for Standardization 

ISU. indexed sequential unmovable (value of DSORG) 

JCL. job control language 

JFCB. job file control block 

JFCBE. job file control block extension for 3800 
printer 

K. 1024 

KEYLEN. key length (operand of DCB) 

LPA. link pack area 

LPALIB. link pack area library 

LRECL. logical record length (operand of DCB) 

LRI. logical record interface 

M. machine control code (value of RECFM) 
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MACRF. macro instruction form (operand of DCB) 

MOD. modify data set (value of DISP) 

MS HI. main storage for highest-level index (operand 
of DCB) 

MSS. Mass Storage System 

MSVC. Mass Storage Volume Control 

MSWA. main storage for work area (operand of DCB) 

NCP. number of channel programs (operand of DCB) 

NOPWREAD. no password required to read a data set 
(value of LABEL) 

NRZI. nonreturn-to-zero-inverted (tape recording 
mode) 

NSL. nonstandard label (value of LABEL) 

NTM. number of tracks in cylinder index for each 
entry in lowest level of master index (operand of DCB) 

OPTCD. optional services code (operand of DCB) 

OS CVOL. operating system control volume 

OS/VS. operating system/virtual storage 

OUTIN. output then input (operand of OPEN) 

PCI. program-controlled interruption 

PDAB. parallel data access block 

PDS. partitioned data set 

PE. phase encoding (tape recording mode) 

PL. PUT macro, locate mode (value of MACRF) 

PM. PUT macro, move mode (value of MACRF) 

PO. partitioned organization (value of DSORG) 

POU. partitioned organization unmovable (value of 
DSORG) 

PRTSP. printer line spacing (operand of DCB) 

PS. physical sequential (value of DSORG) 

PSU. physical sequential unmovable (value of 
DSORG) 

QISAM. queued indexed sequential access method 
QSAM. queued sequential access method 


RACF. Resource Access Control Facility 
RDBACK. read backward (operand of OPEN) 

RDW. record descriptor word 
RECFM. record format (operand of DCB) 

RKP. relative key position (operand of DCB) 

RLSE. release unused space (DD statement) 

RPS. rotational position sensing 

S. standard format records (value of RECFM) 

SDW. segment descriptor word 

SER. volume serial number (value of VOLUME) 

SETL. set lower limit of sequential retrieval (QISAM 
macro instruction) 

SF. sequential forward (operand of READ or WRITE) 

SK. skip to a printer channel (operand of CNTRL) 
SKP. skip erroneous block (value of EROPT) 

SL. IBM standard labels (value of LABEL) 

SMSI. size of main-storage area for highest-level index 
(operand of DCB) 

SMSW. size of main-storage work area (operand of 
DCB) 

SP. space lines on a printer (operand of CNTRL) 

SS. select stacker on card reader (operand of CNTRL) 

SUL. IBM standard and user labels (value of LABEL) 

SVC. supervisor call 
SVCLIB. supervisor call library 

SYNAD. synchronous error routine address (operand 
of DCB) 

SYSIN. system input stream 
SYSOUT. system output stream 

T. track overflow option (value of RECFM); 
user-totaling(value of OPTCD) 

TIOT. task I/O table 

TRC. table reference character 
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TRTCH. track recording technique (operand of DCB) 

U. undefined length records (value of RECFM) 

UCS. universal character set 

UHL. user header label 
UTL. user trailer label 

V. format-V (variable-length) records (value of 
RECFM) 


VB. variable-length, blocked records (value of 
RECFM) 

VBS. variable-length, blocked, spanned records (value 
of RECFM) 

VS. variable-length, spanned records 
VSAM catalog, virtual storage access method catalog 
VTOC. volume table of contents 
XLRI. extended logical record interface 


228 


MVS/XA Data Administration Guide 



Index 


0 

abbreviations 225-228 
ABE error option 78 
abend exit 97-102 
abend installation exit 103 
abnormal termination 

abend installation exit 103 
during open, close, or EOV processing 50 
ESTAE exit 157 
STAE exit 157 
STAI exit 157 

ISO/ANSI/FIPS Version 3 tapes 50 
absolute actual address 
defined 7 

absolute generation name 193 
ACC error option 78 
access method services 

DEFINE command 10 
program use of 11 
access methods 
basic 61-73 
defined 2 
queued 2, 35-68 
selecting 35, 36 
access techniques 
basic 2, 61-73 
queued 2, 35-68 
acronyms 225-228 
actual device addressing 
BDAM 36 
actual track address 
(MBBCCHHR) 
description 7 

use with direct data sets 153 
use with feedback option 153 
address, direct access storage device 
absolute actual 
description 7 
direct 149 
indirect 150 
relative 

description 7 
in directories 132-135 
use with direct data sets 152 
addressing, types of (BDAM) 36 
alias names in a directory 

effect of changing directory entry 141 
specifying 133 
alignment of buffers 120 
allocation, space 

See space allocation 

American National Standard Code for Information 
Interchange 

See ASCII block prefix 
American National Standard Institute 


See ANSI control characters 
American National Standard labels 9 
ANSI control characters 
described 215 

device type considerations 29 
used with chained scheduling 116 
anticipatory buffering 

omitted with basic access technique 61 
with queued access method 65 
ASCII format 

restriction for 7-track tape 29 
translating data from 116 
associated data sets 

restriction with chained scheduling 115 
ATLAS macro 73 

automatic blocking/deblocking with queued access 
methods 65 

automatic cataloging of data sets 5 
automatic error options 
See EROPT 

automatic volume switching 57 
FEOV macro 57, 65, 114 
auxiliary storage 

See data set storage, direct access storage, magnetic 
tape volumes 


B 


backspacing 

BSP macro 203 
CNTRL macro 201 
basic access method 

See also BDAM, BISAM, BPAM, and BSAM 
overlapped I/O 61 
basic access technique 

See also BDAM, BISAM, BPAM, and BSAM 

blocking 61 

deblocking 61 

definition of 61-73 

using BDW 18 

" BCDIC translation to EBCDIC 30 
BDAM data set 

See also basic access method 
See also basic access technique 
access technique 149 
adding records 154-156 
CHECK macro 64 
creating 150 

dynamic buffering 124, 149 
exclusive control for updating 153 
extended search option 153 
feedback option 153 
organization 149 
processing 149-156 
READ macro 62, 63 
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record format 154 

with undefined-length records 27 


selecting an access method 35, 36 

with variable-length records 17-19 


sharing data set 70, 72 

boundary alignment 


spanned variable-length records 19-23 

buffer 120 


SYNAD routine 78 

data control block 46 


updating records 154-156 

BPAM data set 


user labels 81,156 

concatenation 113, 146 


WAIT macro 64 

creating 136-137 


when sharing a data set 70, 72 

defined 2, 131-133 


WRITE macro 63 

EODAD routine 76 


BDW (block descriptor word) 18 

processing 131-146 


BFTEK operand (DCB macro) 

restriction with 


BFTEK = A 20,123 

chained scheduling 144 


BFTEK= R spanned records 62 

DCB abend exit routine 97 

1 

BISAM data set 

fixed-length records, standard format 15 


See also indexed sequential data set 

retrieving member 143 


dynamic buffering 124 

space allocation for 135, 136 


retrieving 174-180 

updating member 144 


sharing a DCB 71 

when sharing a data set 70, 71 


updating 174-181 

BSAM data set 


when sharing a data set 70, 71 

as SYSIN/SYSOUT data sets 105 


BLDL macro 

creating 109, 110 


build list format 139 

creating a BDAM data set 150 


coding example 143 

EODAD routine 76 


description 139 

extending 113 


set 142 

how EODAD routine is entered 76 


BLKSIZE operand (DCB macro) 

overlap of I/O 61, 62, 115 


description 43 

retrieving 110 


effect of data check on 43 

to update the directory 141 

^ i 

for card reader and punch 30 

updating 112 

| 1 

for writing a short block 119 

user labels 83 

V. 

including block prefix 23 

user totaling 86-87 


requirement for direct data set 149 

when sharing a data set 70, 71 


specifying 59, 217 

writing a short block 119 


when ignored 106, 135 

BSP macro 


block count exit routine 94-95 

description 203 


block descriptor word (BDW) 18 

restriction in EODAD routine 76 


block prefix (ISCII/ASCII) records 

BUFCB operand (DCB macro) 120 


buffer alignment 120 

buffer 


block prefix (ISO/ANSI) records 

See also FREEBUF, FREEDBUF, GETBUF, 


with format-D records 24 

RELSE 


with format-F records 17 

acquisition and control 119 


block prefix (ISO/ ANSI/FI PS) records 

alignment 120 

% 

with format-D records 23 

automatic for ISAM 


with format-U records 27 

direct 119,124 

\ 

block prefix records 

dynamic 119, 124 

I 

with format-F records 13 

control 123-130 


block size limitation 

for basic access technique 119, 121 


ISO/ANSI spanned records 24 

length 

1 

ISO/ANSI Version 3 tapes 43 

BUFL operand 120, 186 


block, data 13 

number (BUFNO operand of DCB macro) 115, 


blocking 

120 


automatic 65 

number (BUFNO operand) 121 


defined 13 

releasing 129 


records 

segment 119, 123 


BSAM 38 

truncating 129 


QISAM 38 

buffer pool 


QSAM 39 

See also BUILD, GETPOOL, FREEPOOL 

,1 \ 

with basic access technique 61 

automatic construction 120, 121 


with fixed-length records 14-17 
with spanned records 19 

building 120 
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coding examples 122 
creating 121 
description 120 
explicit 120 
freeing 122-123 
getting a buffer from 129 
returning a buffer to 129 
returning a dynamic buffer to 129 
static 120 
buffering 

anticipatory 

for queued access method 65 
omitted for basic access technique 61 
direct control of 124 
dynamic 119 
exchange 128 
look-ahead 65 
problem program controlled 
BDAM 36 
BPAM 37 
simple 119, 124-128 
BUFL operand (DCB macro) 
for card punch 31 
for constructing a buffer pool 120 
for printer 32 
ISAM 186 

BUFNO operand (DCB macro) 

affecting chained scheduling 115 
affecting performance 115 
constructing a buffer pool 121 
when constructing a buffer pool 120 
when ignored 1Q6 
BUFOFF operand (DCB macro) 
with format-DB records 116 
with QSAM or BSAM 16 
with variable-length records 23-24 
BUILD macro 

description 120 
with ISAM data set 186 
BUILDRCD macro 
description 121 
restriction 21 
usage 20, 21 


0 

CAMLST macro 10 
capacity for direct access 
cylinder 6, 221 
record 6, 150 
track 221 
card punch 

record format 30, 31 
card reader 

record format with 30-31 
relationship with CNTRL macro 201 
restriction with CNTRL macro 201 
carriage control characters 


defined 31,213 

specification of in RECFM field 29 
CATALOG macro 10 
catalog, system 

entering a data set name 10 
OS CVOL 9, 10 
cataloging data sets 
automatic 5 
defined 1 

for a generation data group 193-195 
CCW (channel command word) 
creation by OPEN 47 
PCI flag in 115 
use in simple buffering 124 
chained scheduling 
BSAM 116 
DASD 116 
description 109, 115 
QSAM 116 
restriction with 

calculating record length 117 
CNTRL macro 115 
DOS checkpoint records, embedded on 
tape 115 

format-D records 23 
partitioned data set 144 
SKP option 78 
spooled data sets 115 
3525 Card Punch 115 

changing an address in the data control block 46, 47 
changing the data control block 47 
channel command word (CCW) 

See CCW 
channel programs 

execute (EXCP) 3, 35 
number of (NCP) 62, 106, 115 
CHECK macro 
description 64 
to enter EODAD routine 76 
to update a partitioned data set 144 
to update a sequential data set 112 
use with BDAM 157 
use with SYNAD routine 61,78 
using WAIT instead 
See WAIT macro 
when sharing a data set 70, 157 
with basic access technique 61 
check routine, examining DECB 64 
checkpoint/restart 

check of JFCBFLAG 94 
restriction for LPALIB 94 
CHKPT rhacro 

use in end-of-volume exit routine 94 
CLOSE macro 

description 52-55 

for multiple data sets 54 

for parallel input processing 67-68 

in EODAD routine 76 

restriction with SYNAD 52, 78 

temporary close option 52-55 

TYPE = T 52-55 
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volume positioning 47, 52, 56 
with partitioned data set 141-142 
with STOW macro 141 
closing a data set 52-55 
CNTRL macro 

device dependence 201 
restrictions 

with BSP macro 203 
with chained scheduling 115 
with DOS checkpoint records 201 
concatenation 
data sets 

BPAM 37 
partitioned 146 
sequential 113 
unlike 113 
defined 113,146 
control buffer 

See forms control buffer 
control characters 

See also CNTRL, PRTOV 
ANSI 23,29,116 
carriage 31, 213, 215 
code 213,214 
explained 31 
format-D 23 
format-F 15 
format-U 27 
format-V 19 
ISO/ANSI/FIPS 15 
machine 29, 116, 213, 214 
specifying 29, 213 
with fixed-length records 15 
with undefined-length records 27 
with variable-length records 19 
control section, dummy (DSECT) 46 
count area 

count data format 8 
count key data format 6 
in device overhead 219 
ISAM index entry format 162 
cross reference table with direct data sets 150 
CSECT statement 

with DCBD macro 46 
cylinder 

allocation by 217 
capacity 6, 218 
index 

calculating space requirements for 166 
definition 160, 162 
overflow 

calculating space for 166, 170 
defined 163 

specifying size via CYLOFL parameter 167 
CYLOFL operand (DCB macro) 
allocating ISAM data set 167 
creating ISAM data set 163 


D 


D-format records 

See format-D records 
data access techniques 
See access techniques 
data checks 

effect on BLKSIZE 43 
data control block 
See DCB 

data definition name (ddname) field (DD statement) 45 
data definition statement 
See DD statement 
data event control block 
See DECB 
data management 

introduction 1, 71, 72 
data mode processing 

relationship with buffers 123 
data set 

characteristics 1 
description 43 
disposition (DISP) operand 
description 45 

overridden by OPEN macro 56 
identification 3 

label (LABEL) field of DD statement 45 
like characteristics 113, 146 
name 3 

name (DSNAME) field 45 
organization 

DSORG operand (DCB macro) 44 
RECFM (record format) 13-28, 31 
routing through the input/output stream 105-107 
security 205, 206 
space allocation 

a direct data set 150 
estimation 218-221 
indexed sequential data sets 166-174 
partitioned data sets 135, 136 
specifying 217-218 

space allocation on direct access volumes 136 
storage 

direct access 5 
magnetic tape 8 
SYSIN 105-107 
SYSOUT 105-107 
unlike characteristics 113, 146 
unmovable 

resulting from use of MMBBCCHHR 8 
data set control block 
See DSCB 

DCB (data control block) 
abend exit 

description 97-99 
when available 75 
where specified 75 
attributes of, determining 41 
changing 47 
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changing an address in 46, 47 
creation by DCB macro 4, 41 
description 41-42 
dummy control section 46 
exit 

description 88 
when available 75 
when used by SYSIN/SYSOUT 105 
where specified 75 
fields 43 
modifying 41, 45 
operand of DD statement 45 
primary sources of information 41 
sequence of completion 42 
use 4 

when sharing a data set 69 
DCB abend exit 97-99 
DCB macro 
QISAM 38 

DCBBLKSI field in DCB 32, 119 
DCBD macro 46 
restriction 46 
use 46 

DCBLPDA field of DCB 190 
DCBNCRHI field of DCB 189 
DCBPRECL field of DCB 19 
DCBSYNAD field of DCB 47 
DD statement 
fields 43 

relationship to DCB 41 
relationship to JFCB 41 
use of 4 

DD statement fields 45 
DDNAME operand 

See data definition name field 
deblocking, automatic 65 
DECB (data event control block) 
description 65 
use of 112 

defer nonstandard input trailer label exit 95 
DEFINE command 10 
defining an FCB image 95, 96 
delete option 

restriction when updating a sequential data set 112 
restriction with RKP 185 
use with SETL 191 
deleting 

indexed sequential data set records 184 
member name using STOW macro 141 
DEN (tape density) 29-30 
density, tape 29-30 
DEQ macro 70,71, 177 
descriptor word 

See block descriptor word, record descriptor word, 
segment descriptor 
determinate errors 49 
DEVD operand (DCB macro) 

device-class independence considerations 59 
restriction with SYSOUT data sets 106 
specifying 29 
with BDAM 150 


with SYSOUT data sets 106 
device control for sequential data sets 201-204 
device independence 58-59 
device type 

considerations for data format 
sequential organization 28, 33 
device-dependent macros 201 
DEVTYPE macro 188 
direct access device 
characteristics 44 
direct access storage devices 
See DASD 
direct access volume 

access mechanism 6 
description 5 
device characteristics 6-44 
labels 6 

RECFM (record format) 28, 31 
record format 28-29, 33 
record format (RECFM) 5 
track addressing 7 
track format 6 
track overflow 7 
track, defined 6 
write validity check 44 
direct addressing 149 
direct data set 

See BDAM data set 
direct organization 

See BDAM data set 
directory 

See BPAM data set 
directory, partitioned data set 
creation 37 
DISP operand 
action of 57 
description 45, 56 
for extending sequential data set 113 
for indexed sequential data set 183 
for partitioned data set 141 
for tape 42, 85 

when DISP = SHR for sharing data sets 70, 177 
when passing a generation 198 
when updating the directory 141 
DOS (disk operating system) 
embedded checkpoint records 
restriction with BSP 203 
restriction with chained scheduling 115 
restriction with CNTRL 201 
restriction with POINT 204 
DSCB (data set control block) 
contents of 211 
data set label 209-212 
data set security byte 205 
described 6, 211 

index (format-2) DS2HTRPR field of 189 
DSECT statement 46 
DSNAME operand 

DD statement 45, 140, 142 
DSORG operand (DCB macro) 

CLOSE TYPE = T 54 
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described 44 
direct data set 150 
indexed sequential data set 163 
partitioned data set 136, 140, 141 
sequential data set 109, 110 
dummy control section 
for DCB 46 
dummy data set 

restriction with parallel input processing 67 
dummy records 

with direct data set 151, 154 
dynamic buffering 

buffer control 121, 149 
for direct data set 149 
for ISAM dataset 164, 176 
specifying 121 


E 


EBCDIC (extended binary coded decimal interchange 
code) 

for magnetic tape volumes 9 
record format dependencies 13-31 
translation to and from ASCII 116 
translation to and from ISCII/ASCII 1, 9, 63, 65, 
66 

embedded index area 166, 167 
end-of-block 
See EOB 

end-of-data indicator 55 
end-of-data routine 

See EODAD routine 
end-of-sequential retrieval 
See ESETL 
end-of-volume 

exit routine 94 
forcing 57, 58 
processing 55-58 

routines, relationship with DCB abend exit 97, 99 
when EODAD routine entered 76, 77 
ENQ macro 

when sharing a data set 70, 71 
EOB (end-of-block) 

fixed-length records 16 
EODAD (end-of-data) routine 

changing address of in DCB 46-47 
specifications 76-77 
with basic access technique 61 
with BSP macro 203 
with concatenated data sets 114 
with GET macro 65 
with queued access technique 65 
EROPT (automatic error options) operand (DCB 
macro) 78 


error 

analysis routine (SYNAD) 77-79 
determinate 49 
handling 72 
indeterminate 49 
options, automatic 78 
uncorrectable 77 
error routine 

See SYNAD routine 

ESETL (end-of-sequential retrieval) macro 
description 191 
in EODAD routine 76, 77 
when sharing a data set 71 
ESTAE exit, abnormal termination 157 
exceptional condition code 
See condition, exceptional 
exchange buffering 128 
exclusive control 

updating direct data sets 153 
when sharing direct data sets 71 
EX CP (execute channel program) 3 
EXCP macro 35 

execute channel program (EXCP) 3 
exit list 79-81 
list 81 
exit routine 

block count 94-95 

conventions 82 

DCB (data control block) 88 

DCB abend 97-102 

defer nonstandard input trailer label 95 

end-of-data 76-77 

end-of-volume 94 

FCB image 95 

identified by DCB 75 

JFCBE 93 

list 79 

QSAM parallel input 93 
register contents on entry 82 
standard user label 82-86 
synchronous error (SYNAD) 77-79 
user totaling 86 

EXLST operand (DCB macro) 77, 79 
EXTEND operand (OPEN macro) 
device independence 58 
extending sequential data set 113 
indexed sequential data set 183 
QISAM use 51 
specifying 42 

use with SYSIN/SYSOUT 51 
extended binary coded decimal interchange code 
See EBCDIC 

extended logical record interface (XLRI) 27 
extended search option 
for direct data sets 153 
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F-format records 

See format-F records 
FCB (forms control buffer) 
image 

exit 95 

identification in JFCBE 93 
relationship with SETPRT 202 
FCB images 

formats of 202 
feedback 

option 153 

with BDAM READ macro 63 
with BDAM WRITE macro 64 
FEOV macro 

description 57, 58 

ignored for SYSIN/SYSOUT data sets 58 
restriction with spanned records 20, 57 
restriction with trailer label exit 85 
to enter EODAD routine 76 
file access exit 51 
file mark, restriction 203 
FIND macro 

description 139-140 
in EODAD routine 76, 77 
updating a partitioned data set 144 
when sharing a data set 71 
fixed-length records 
description 14-17 
with parallel input processing 66 
force end-of-volume 
See FEOV macro 

format-D records, restriction with chained 
scheduling 23 
format-F records 

description 13-17 
ISO/ANSI tapes 17 
ISO/ANSI FIPS tapes 15 
standard format 14-15 
with card reader and punch 30-31 
with parallel input processing 66 
format-S records 

extended logical record interface 27 
segment descriptor word 24 
format-U records 

calculating record length 117 
description 27 

restriction for ISO/ANSI tapes 28 
with card reader and punch 30 
with parallel input processing 66 
format-V records 

block descriptor word 18 
description 18-23 
record descriptor word 19 
segment control codes 21 


segment descriptor word 21 
spanned 19 
with card punch 30-31 
with parallel input processing 66 
forms control buffer 
See FCB 

FREE operand 55 
FREEBUF macro 
description 129 
example 178 
for ISAM 176 
to control buffers 119 
FREEDBUF macro 
description 129 
when sharing data sets 157 
FREEPOOL macro 

when issued for card punch data set 31 
when issued for printer data set 32 
when used 122 

full-track-index write option 164 


G 


generation data group 

absolute generation name 193 
building an index 199 
creating a new 197, 198 
defined 5, 193 

entering in the catalog 193, 194, 195 
naming conventions 

Version 3 labels 196 
relative generation name 193 
retrieving 199 
generation data set 193 
generation index 193 
generation number field 
Version 3 labels 196 
generation numbers 
relative 193, 197 
GET macro 

description 65 
in EODAD routine 76 

restriction with spanned records to enter EODAD 
routine 76 

updating a sequential data set 112 
when sharing a data set 70 
with format-U records 28 
with parallel input processing 66, 67 
GETBUF macro 
description 129 
to control buffers 119 
GETPOOL macro 

with ISAM data set 186 
glossary 225-228 
grouping related control blocks 61 
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I 



header label 

user 82, 86, 212 



ID CAMS program 218 
IEBCOPY program 145, 146 
IECOENTE macro 

nonspecific tape volume mount exit 89 
IECOEVSE 

I EH ATLAS program 73 
IEHLIST program 167, 189 
IEHMOVE program 133, 134 
IEHPROGM program 198 
IHADCB DSECT 
label 46 

independent overflow area 
description 163 
specifying 169 
indeterminate errors 49 
index 
area 

calculating space for 166-167 
creation of 159 
cylinder 

calculating space for 166 
overflow area 163 
master 

calculating space for 166 
using 160 

space allocation for 39 
track 

calculating space for 167 
track 160 

indexed sequential data set 
adding records 182-183 
areas 159-162, 163, 166-174, 186-189 
allocating space for 166-174, 186-189 
index 161-162 
overflow 163 
prime 160 

buffer requirements 186 
creation 163-166 
deleting records 184 
device control 189-191 
full-track-index write option 164 
inserting new records 182 
new records at the end 182 
retrieving 174-177 


SYNAD routine 79 
updating 174-181 
indirect addressing 150 
INOUT operand (OPEN macro) 42, 51, 204 
INPUT operand (OPEN macro) 42, 51 
input/output devices 
magnetic tape 29 
with sequential data sets 

card reader and punch 30, 31 
direct access 33 
magnetic tape 30 
printer 32 
input/output errors 

recovering from 73 
installation exit 

ISO/ANSI/FIPS Version 3 tapes 50 
with RACF 207 
interrecord gaps (IRGs) 13 

IOB, relationship with SYNAD routine for BDAM 78 

IRG (interrecord gap) 13 

ISAM 

See indexed sequential data set, BISAM, QISAM 
ISCII/ASCII block prefix 
restriction 13, 15, 23 
with format-D records 23 
with format-F records 13-16 
with format-U records 27 
ISCII/ASCII format 

translating data from 1, 13, 65 
translating data to 1, 13, 63, 66 
ISCII/ASCII tape 

buffer alignment 120 
ISO/ANSI tape 
Version 3 

block size limitation 43 
ISO/ANSI/FIPS control characters 
with format-D records 23 
with format-F ISO/ANSI/FIPS tape records 15 
ISO/ANSI/FIPS tape 

fixed-length records 15 
undefined-length records 27 
variable-length records 23 




JES (job entry subsystem) 105-107 
JFCB (job file control block) 41, 49 
JFCBE (job file control block extension) 
exit 93 

JFCBFLAG 94 
job file control block 41, 49 
job file control block extension (JFCBE) 
exit 93 
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K 


key 

class 190 

for direct access devices 7 
for indexed sequential data sets 159-162 
RKP (relative key position) for indexed sequential 
dataset 163,185,186 

use of when adding records to indexed sequential 
data set 182 

use of when maintaining an indexed sequential data 
set 184 

use of when retrieving records from an indexed 
sequential data set 176-181 
KEYLEN operand (DCB macro) 
description 44 
for direct access device 33 
for direct data set 150 
specifying 59 
KN 

See WRITE with KN 
KU 

See READ with KU 


0 

label exits 82-86 

LABEL parameter in DD statement 
description 45 

specifying password protection 205 
specifying standard labels 84 
label symmetry conflict 

ISO/ANSI Version 3 tapes 51 
label validation exit 50 
labels 

direct access 209 

data set control block 209-212 
format 209 
user label groups 211 
volume label group 209-211 
LEAVE option 

for close processing 52, 54 
for concatenated data sets 114 
for end-of-volume processing 56, 57 
for forced end-of-volume processing 57 
length checking 14 
link field 186, 187 
link pack area 
library 

restriction for checkpoint 94 
load mode 
BDAM 

when sharing data sets 157 
QISAM 38 

in SYNAD routine 79 
when sharing a DCB 72 


load module 

attribute assignment 
fields 41 

loading an indexed sequential data set 164 
locate mode 

defined for buffering 123 

example with simple buffering 126, 127, 128 

relationship with buffers 123 

to process records that exceed 32760 bytes 21 

to update a member with QSAM 144 

with GET macro 

creating a sequential data set, coding 
example 111 

simple buffering 109, 111, 125-128 
with parallel input processing 
example 68 

simple buffering 124-128 
logical record interface (LRI) 20 
look-ahead buffering 65 
LPALIB 

restriction for checkpoint 94 
LRECL operand (DCB macro) 
coding in K units 27 
described 44 
device dependence 59 

to process records that exceed 32760 bytes 21 
with BDAM 150 
with BSAM 119 
with ISAM 

buffer requirements 188 
data set creation 163 
with PUT macro 66 
with SYSOUT data set 105 
LRI (logical record interface) 
spanned records 20 


M 


machine control characters 29, 116 
MACRF operand (DCB macro) 
device independence 59 
dynamic buffering 179 
for BDAM 150 

relationship with WAIT macro 64 
to update a member using QSAM 144 
when sharing a data set 70, 72 
magnetic tape volumes 
defined 8 
density 29-30 
labels 

American National Standard 9 
none 5 
nonstandard 5 
standard 5 
user 82-86 
organization 8 
positioning 

during close processing 52-55 
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during end-of-volume processing 56, 57 
RECFM (record format) 8-28, 29, 31 
serial number 9 
tapemarks 9 
mass storage system 146 
master catalog 10 
master index 162 
MBBCCHHR 

See actual track address 
mode 

See also MACRF operand 
load (QISAM) 38 
resume load mode 38 
scan (QISAM) 38 
modes, processing 

See data mode, locate mode, move mode, substitute 
mode 

modifying the data control block 41, 45 
move mode processing 

relationship with buffers 123 

use instead of exchange buffering 128 

with GET macro 

creating a sequential data set 109 
simple buffering 109, 125-128 
with parallel input processing 66 
with PUT macro 

creating a sequential data set 109 
simple buffering 109, 125-128 
MSS (Mass Storage System) 
staging 146 

MSVGP parameter on JCL statement 218 
MSWA operand (DCB macro) 188 
multiple data sets 
closing 48 
opening 48 

processing for QISAM 120 
multitasking mode, sharing data sets 48, 50, 72 
multivolume data set 

with NOTE macro 203 


N 


names 

data set 3 

generation data group 5, 193, 194, 195 
NCP operand (DCB macro) 62, 106, 115 
nonsequential processing of sequential data 38 
nonspecific tape volume mount exit 88-90 
general register rules 90 
IECOENTE macro parameter list 89 
return codes 88 
how specified 89 
nonstandard tape labels 5, 8 
note list 134 
NOTE macro 

ABS parameter 203 
description 203 
restriction with 203 


BSP macro 203 
multi volume data sets 203 
updating a sequential data set 112 
use with partitioned data set updating 144 
NTM operand (DCB macro) 162 
null segment 22 


o 


offset reading 62 
OMR 

See optical mark read 
OPEN macro 

considerations for 49, 50 
description 51-53 
for parallel input processing 67 
for simultaneous opening of multiple data sets 48 
for updating a sequential data set 112 
functions 42, 51-53 
used for more than one data set 48 
volume positioning for EOV 56 
OPEN/EOV volume security/verification exit 90-93 
general register rules 93 
IECOEVSE 91 
return codes 91 
how specified 91 
opening a data set 47-50 
OPTCD operand (DCB macro) 
device dependence 116 
request user totaling (OPTCD ~T) 86 

with BDAM 151 
with ISAM 164 

with ISCII/ASCII tapes (OPTCD = Q) 65, 66 
OPTCD-H 

embedded checkpoints, DOS tapes 
positioning DOS tapes 201 
MSS staging 146 
OPTCD = M (master index) 162 
OPTCD = T (user totaling) 86 
OS CVOL 9, 10 

OUTIN operand (OPEN macro) 42, 51, 204 
OUTINX operand (OPEN macro) 42, 51, 58 
output mode, defined 124 
OUTPUT operand (OPEN macro) 42, 51, 204 
when using POINT macro 204 
output stream 105-107 
overflow 

area 159, 163 
chain 182 
cylinder 

See cylinder overflow 
independent area 163 
PRTOV macro 202 
records 163 
track 

description 7 

restriction on BSP macro 203 
restriction with parallel input processing 67 
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restriction with RPS feature 117 
overflow, track 
restrictions 
ISAM 38 

overlap of input/output 

performance improvement 115 
with partitioned data sets 144 
with queued access method 65 
with sequential data sets 112 


0 

padded record 24 

end-of-block condition 16 
paging environment, related control block group 61 
parallel data access block (PDAB) 67, 93 
parallel input processing 66-68, 93 
parameter list 

contents of 97 

use of by DCB abend exit routine 97-99 
partitioned data set 

See also BPAM data set 
general description 37 
PASSWORD data set 205 
password protection 205, 206 
PC (card punch) record format 30-31 
PCI flag 115 

PDAB (parallel data access block) 67, 93 
PDS 

See BPAM data set 
performance improvement 115 
POINT macro 

description 204 
in EODAD routine 76 
relationship to 
BSAM 38 
restriction with 

BSP macro 203 
multivolume data sets 204 
updating a partitioned data set 144 
updating a sequential data set 112 
prefix, block 

See block prefix 
prefix, key 190 
prime data area 

description 159, 160 
space allocation for 166, 168 
printer 

overflow (PRTOV macro) 202 
record format with 32 
program, describing the processing 2-102 
PRTOV macro 
description 202 
device dependent 59 
when macro will not function 202 
PUT macro 

description 66 
locate mode 123-128 


processing mode 123 
used to create a sequential data set, coding 
example 110 
with format-U records 28 
with indexed sequential data set 182-183 
with simple buffering 125-128 
PUTX macro 

description 66 

device independence 59 

UPDAT mode 127 

updating a sequential data set 112 

when sharing a data set 70 

with format-U records 28 

with simple buffering 125-128 


Q 


QISAM data set 
See also ISAM 
EODAD routine 76 
scan mode 176 
sharing 70, 72 
SYNAD routine 77-79 
using common buffer pool 120 
QSAM (queued sequential access method) 
See also queued access technique 
creating a BDAM data set 150 
parallel input processing 66-68 
performance improvement 115 
restriction with spanned records 20 
spanned variable-length records 20 
SYS IN/S YSOUT data sets 105 
to update a directory 141 
to update a member 144 
user labels 83 
user totaling 86-87 
when sharing a data set 70, 71 
with card punch 31 
with printer 32 
queued access method 
defined 65 

queued access technique 
buffer control 119, 123 
defined 35 
introduced 2 
processing modes 

See data mode processing 


R 


RACF 

installation exit 207 
protection 206, 207 
RD (card reader) 30-31 
RDBACK operand (OPEN macro) 
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label exit routine 8 5 
opening magnetic tape volume 42 
restriction for variable-length records 51 
restriction with SYSIN/SYSOUT data sets 51 
RDW (record descriptor word) 

data mode exception for spanned records 19 
extended logical record interface 27 
variable-length records format-D 23, 24, 25 
when replaced by segment descriptor word 21 
read backward 

SB operand of READ macro 62 
READ macro 
description 62 
device independence 59 
in SYNAD routine 78 
restriction in EODAD routine 76 
to enter EODAD routine 76 
to update existing records 176 
updating a partitioned data set 144 
updating a sequential data set 112 
when sharing a data set 70, 157 
with basic access method 62 
with format-U records 28 
with KU (key, update), in coding example 178 
RECFM (record format) 
fixed-length 17 
fixed-length for ISO/ANSI 17 
spanned variable-length 19 
undefined-length 27 
variable-length 17 -24 
RECFM operand (DCB macro) 
description 44 
for sequential data sets 28 
selecting 14 
with card punch 30-31 
with card reader 30-31 
with control character 29 
with direct access storage device 33 
with magnetic tape 29-30 
with printer 32 

with sequential organization 28-29 
record blocking 
See blocking 
record descriptor word 
See RDW 
record format 
See RECFM 
record format (RECFM) 
fixed-length 14 

fixed-length for ISO/ANSI/FIPS 15 
fixed-length standard 14 

record length (LRECL) operand (DCB macro) 44, 59 
relative addressing 
BDAM 36 
relative block address 

with direct data set 152 
with feedback option 153 
relative generation name 193-197 
relative key position (RKP) operand (DCB 
macro) 163, 185, 186 
relative track address 


defined 8 

with direct access 152 
with feedback option 153 
releasing data sets and volumes 55 
RE LEX macro 

exclusive control 157 
when sharing data sets 157 
RELSE macro 
defined 129 

to terminate buffer processing 119 
reorganization of indexed sequential data set 183 
reorganization statistics (ISAM) 39 
REREAD option 56, 57 
restart end-of-volume exit routine 94 
restriction with 2540 
restrictions 

on ASCII records 

on 7-track tape 29 
on chained scheduling with 

calculating record length 117 
CNTRL macro 115 
DOS checkpoint records 115 
format-D records 23 
partitioned data set 144 
SKP option 78 
spooled data sets 115 
track overflow 117 
3525 Card Punch 115 
on CNTRL macro 

with BSP macro 203 
with chained scheduling 115 
with DOS checkpoint records 201 
on DCB usage 48-49 
on DCBD macro usage 46 
on DOS checkpoint records 115, 201-204 
on format-D records with chained scheduling 23 
on ISO/ANSI records 
block prefix 23 
on ISO/ANSI/FIPS records 
block prefix 15, 23 
on NOTE macro with 
BSP macro 203 
multivolume data sets 203 
on POINT macro with 
BSP macro 203 
multivolume data sets 204 
on reading concatenated data sets backward 114 
on user label exit routines 82-86 
resume load 38, 163, 166, 183 
retrieving a generation 199 
return codes 

with block count exit 94, 95 
with user labels 84 
RETURN macro 

relationship in SYNAD routine 78 
REWIND option 

for CLOSE macro 52 
for FEOV macro 57 
RKP (relative key position) operand (DCB 
macro) 163, 185, 186 
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RLSE parameter 
DD statement 53 

RORG1, RORG2, RORG3 fields of the DCB 184 
routing data sets through the input/output 
stream 105-107 
RPS (rotational position sensing) 

restriction with track overflow records 
variable-length records 18 
when calculating record length 117 
R0 record 6, 150 


0 

save area 

user totaling 87 
scan mode 38 
for QISAM 

issuing PUTX 176 

scheduling of input/output streams 105 
SDW (segment descriptor word) 
format-S records 24 
search option, extended 153 
secondary storage 

See data set storage, direct access storage, magnetic 
tape volumes 
security 205, 206 
segment 

buffer 119,123 
control code 21 
descriptor word 

for spanned records 21 
indicating a null segment 22 
null 22 

segment descriptor word (SDW) 
format-S records 24 
selecting an access method 35, 36 
sequential data set 

See also BPAM, BSAM, and QSAM data sets 
creation 109, 110 
extending 113 
retrieving 110 
updating 112 
sequential organization 
defined 2 

device control 201 -204 
device independence 58-59 
SETL macro 

in EODAD routine 76, 77 
when sharing a data set 71 
SETPRT macro 

changing printer control information 202 
relationship with 3800 printing subsystem 202 
SETPRT routine 95 
sharing data sets 69-71 
simple buffering 

description 124-128 
with parallel input processing 66, 67 
SKP option 78 


SMS1 operand (DCB macro) 189 
SMSW operand (DCB macro) 188 
space allocation 

BPAM data set 37 
estimating requirements 218-221 
for a direct data set 150 
for a partitioned data set 135, 136 
for an indexed sequential data set 166-174 
QISAM data set 39 
specifying 217-218 
spanned records 

basic direct access method 22 

considerations for 20 

logical record interface 20 

restriction with parallel input processing 67 

restriction with SYS IN data sets 21, 106 

sequential access method 19 

variable-length 19 

spooling of SYSIN and SYSOUT data sets 
how to 105-107 
restriction 115 
stacker selection 

control characters for 14, 31, 214 
STACK operand 31 
using CNTRL macro 201 
STAE exit 157 
STAI exit 157 

standard format for fixed-length records 14 
standard labels 

direct access volumes 6, 209 
magnetic tape volumes 5, 8 
statistics reorganization (ISAM) 39 
storage 

See direct access storage, magnetic tape volumes 
STOW macro 

description 141 

restriction with DCB abend exit 97 
when sharing a data set 71 
subpool 0, when shared 157 
substitute mode 

defined for buffering 124 
switching, volume 
automatic 

restriction with concatenated data sets 114 
with end-of-volume 56 
with FEOV macro 57 
with GET macro 65 
initiated by CHECK 64 
SYNAD field, programming consideration 59 
SYNAD routine 

changing address in DCB 46 

description 77-79 

macros used in 72, 73 

programming consideration 59 

relationship with DECB 65 

relationship with SETL option 191 

relationship with SYSIN/SYSOUT data sets 107 

temporary close restriction 52 

when adding records to ISAM data set 183 

when sharing a data set 72 

with basic access technique 61 
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with queued access technique 65 
SYNADAF macro 
description 72, 73 
examples 111 
use in SYNAD routine 79 
SYNADRLS macro 
description 73 
examples 111 
use in SYNAD routine 79 
SYNCDEV macro 204 
synchronous error routine exit 
See SYNAD routine 
SYS IN data set 

FEOV macro ignored for 58 
restriction with 

chained scheduling 115 
parallel input processing 67 
spanned variable-length records 21 
user totaling 86 

routing data through input stream 105-107 
SYSOUT data set 

FEOV macro ignored for 58 
restriction with 

chained scheduling 115 
label exits 85 

spanned variable-length records 21 
user totaling 86 * 

routing data through output stream 105-107 
system input stream 105-107 
system output stream 105-107 
system output writer 105-107 
SYSLIMAGELIB 

adding band names/aliases 202 
character arrangement table modules 202 
FCB images 202 
UCS image tables 202 
UCS images 202 
SYSLIMAGELIB data set 
search of 95 


0 

table reference character 
See TRC 

table reference character (3800) 31, 32 

tape 

See magnetic tape volumes, paper tape reader 
tapemarks 9 
temporary close 52-55 
totaling area, user totaling exit routine 86-87 
track 

addressing 7 
defined 6 
format 

count data format 6 
count key data format 6 
index 159-162, 166 
overflow option 


description 7 

restriction of BSP macro 203 
restriction with BDAM 156 
restriction with parallel input processing 67 
restriction with RPS feature 117 
restriction with variable-length records 18 
track addressing, relative 
BDAM 36 
track overflow 
restrictions 
ISAM 38 
trailer labels 
user 82, 86 

TRC (table reference character 3800) 19 

TRTCH operand (DCB macro) 30 
TRUNC macro 
description 129 

to terminate buffer processing 119 
truncated blocks, format-F records 15 
truncated format-U record 28 
TTR 

See address, direct access storage device, relative 
TYPE = T operand 52-55 


u 


U -format records 

See format-U records 
UCS (universal character set) image 
relationship with SETPRT 202 
UHL (user header label) 82-86 
unblocking records 
BPAM 37 
BSAM 38 
QISAM 38 
QSAM 39 

undefined length records 
See format-U records 
UNIT operand 

DD statement 45 
unlabeled magnetic tape 5-9 
UPDAT option 

See also update mode 

EODAD routine entered for BSAM 76 

opening a data set 42 

restriction with 

SYSIN/SYSOUT data sets 51 
updating a sequential data set 112 
with spanned records 20 
update mode 

See also UPDAT option 
with format-U records 28 
with PUTX 124 
with simple buffering 127 
user catalog 10 
user header label (UHL) 82-86 
user label exit routine 
description 82-86 
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exit list entry 83 

restriction for data sets on volumes without standard 
labels 85 

restriction for SYSOUT data sets 85 
with read backward 83, 85 
user totaling exit routine 
description 86-87 
exit list entry 86 
how specified 86 
image area address 87 
relationship with end-of-volume exit 94 
restricted to BSAM, QSAM 86 
save area 87 
totaling area 86-87 

variable-length and spanned records 87 
user trailer label (UTL) 82-86 
utility programs 
IDCAMS 218 
IEBCOPY 146 
IEHATLAS 73 
IEHLIST 189 
IEHMOVE 134 
IEHPROGM 167, 198 
initializing direct access volume 6 
UTL (user trailer label) 82-86 


0 

V-format records 

See format-V records 
validation suppression exit 51 
variable-length record (format-D) 23-24 
variable-length record (format-S) 23-24 
variable-length record (format-V) 
description 18 
segments 18, 19 
spanned 

description 19-23 

restrictions with SYSIN and SYSOUT data 
sets 21 

special considerations, with user totaling 87 
with parallel input processing 66 
version increment of generation data group 194 
version number field 

Version 3 labels 196 
VIO data set 36 
volume 

defined 5 
disposition 

See DISP operand 

identification operand (DD statement) 45 
index 

See index 
initializing 6 
labels 


See labels, direct access 
magnetic tape 

See magnetic tape volumes 
positioning 52-57 
switching 57, 65, 114 
table of contents 
See VTOC 

volume access exit 51 
VS AM catalog 

generation data group base created in 193 
VTOC (volume table of contents) 
description 5 
DSCB 211 

for ISAM data set 161 
pointer 211 


w 


WAIT macro 

description 64 
example 178 

when sharing a data set 157 
with basic access method 
BDAM 64 
BISAM 64 

with basic access technique 
BDAM 155, 157 

with QSAM parallel input processing 66 
WRITE macro 

add form 150,156 
description 63 
for format-U records 28 
in EODAD routine 76 
in SYNAD routine 78 
programming consideration 59 
update form 154 

updating a concatenated partitioned data set 144 
updating a partitioned data set 144 
updating a sequential data set 112 
used with BDAM 150 
used with note list 135 
when sharing a data set 70, 157 
with basic access technique 61 
with K (key) 176, 179 
with KN (key, new) 180, 182, 185 
writing a short block 119 
write validity checking 44 


x 


XLRI (extended logical record interface) 27 
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Numerics 


1600 BPI 30 

2305-2 Fixed Head Storage 

programming considerations 156 
2540 Card Read Punch 

punch error correction 31 
3211 printer 

SETPRT macro 202 
3262 model 5 printer 
SETPRT macro 202 
3330 Disk Drive 
capacity 219 
overhead formula 220 
3333 Disk Storage 
capacity 219 
overhead formula 220 
3340 Disk Storage 
capacity 219 
overhead formula 220 
3350 Disk Storage 
capacity 219 


3375 Disk Storage 
capacity 219 
overhead formula 220 
3380 Disk Storage 
capacity 219 
overhead formula 

3380 Models AD4 and BD4 Disk Storage 
capacity 219 
overhead formula 220 
3380 Models AE4 and BE4 Disk Storage 
capacity 219 
overhead formula 220 
3525 Card Punch 

chained scheduling ignored 115 
record format 31 
3800 Printer 

JFCBE exit for 93 
table reference character 19> 32 
4245 printer 


SETPRT macro 

202 

4248 printer 



SETPRT 

macro 

202 

7-track tapes 

30 


800 BPI 30 



9-track tapes 

30 
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